Add 'global' option to 'no indirect'

[perl/modules/indirect.git] / lib / indirect.pm

diff --git a/lib/indirect.pm b/lib/indirect.pm
index 1eac9b92e896a8b20f5dca7a06abf0bad6a20341..c2854689ada8bd83045ebd52c063c230dabb9690 100644 (file)
--- a/lib/indirect.pm
+++ b/lib/indirect.pm
@@ -38,11 +38,11 @@ BEGIN {
     no indirect ':fatal';    # or 'FATAL', or ':Fatal' ...
     if (defied $foo) { ... } # croaks, note the typo
 
-    # From the command-line
-    perl -M-indirect -e 'my $x = new Banana;' # warns
+    # Globally enabled from the command-line
+    perl -M-indirect=global -e 'my $x = new Banana;' # warns
 
-    # Or each time perl is ran
-    export PERL5OPT="-M-indirect"
+    # Or globally enabled each time perl is executed
+    export PERL5OPT="-M-indirect=global"
     perl -e 'my $y = new Coconut;' # warns
 
 =head1 DESCRIPTION
@@ -72,7 +72,7 @@ BEGIN {
 
 =head1 METHODS
 
-=head2 C<< unimport [ hook => $hook | ':fatal', 'FATAL', ... ] >>
+=head2 C<< unimport [ 'global', hook => $hook | 'fatal' ] >>
 
 Magically called when C<no indirect @opts> is encountered.
 Turns the module on.
@@ -91,7 +91,28 @@ If and only if the object is actually a block, C<$_[0]> is assured to start by C
 
 =item *
 
-Otherwise, a warning will be emitted for each indirect construct.
+If none of C<fatal> and C<hook> are specified, a warning will be emitted for each indirect construct.
+
+=item *
+
+If C<@opts> contains a string that matches C</^:?global$/i>, the pragma will be globally enabled for B<all> code compiled after the current C<no indirect> statement, except for code that is in the lexical scope of C<use indirect>.
+This option may come indifferently before or after the C<fatal> or C<hook> options, in the case they are also passed to L</unimport>.
+
+The global policy applied is the one resulting of the C<fatal> or C<hook> options, thus defaults to a warning when none of those are specified :
+
+    no indirect 'global';                # warn for any indirect call
+    no indirect qw<global fatal>;        # die on any indirect call
+    no indirect 'global', hook => \&hook # custom global action
+
+Note that if another policy is installed by a C<no indirect> statement further in the code, it will overrule the global policy :
+
+    no indirect 'global';  # warn globally
+    {
+     no indirect 'fatal';  # throw exceptions for this lexical scope
+     ...
+     require Some::Module; # the global policy will apply for the
+                           # compilation phase of this module
+    }
 
 =back
 
@@ -101,19 +122,28 @@ sub unimport {
  shift;
 
  my $hook;
+ my $global;
  while (@_) {
   my $arg = shift;
   if ($arg eq 'hook') {
+   last if $hook;
    $hook = shift;
   } elsif ($arg =~ /^:?fatal$/i) {
+   last if $hook;
    $hook = sub { die msg(@_) };
+  } elsif ($arg =~ /^:?global$/i) {
+   $global = 1;
   }
-  last if $hook;
  }
  $hook = sub { warn msg(@_) } unless defined $hook;
 
  $^H |= 0x00020000;
- $^H{+(__PACKAGE__)} = _tag($hook);
+ if ($global) {
+  delete $^H{+(__PACKAGE__)};
+  _global($hook);
+ } else {
+  $^H{+(__PACKAGE__)} = _tag($hook);
+ }
 
  ();
 }
@@ -122,10 +152,12 @@ sub unimport {
 
 Magically called at each C<use indirect>. Turns the module off.
 
+As explained in L</unimport>'s description, an C<use indirect> statement will lexically override a global policy previously installed by C<no indirect 'global', ...> (if there's one).
+
 =cut
 
 sub import {
- $^H{+(__PACKAGE__)} = undef;
+ $^H{+(__PACKAGE__)} = _tag(undef);
  ();
 }