X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Findirect.git;a=blobdiff_plain;f=lib%2Findirect.pm;h=fd488e78c91a093159e9346d389fa5c9872f8f98;hp=ff3d34e02b2e8ad8f608f9b22d715a3dcfcad414;hb=a35bc34a3dbaebb6510df744d87151739d951578;hpb=c88f53009246bbc1af1789f746acc5d841fc0ae8

diff --git a/lib/indirect.pm b/lib/indirect.pm
index ff3d34e..fd488e7 100644
--- a/lib/indirect.pm
+++ b/lib/indirect.pm
@@ -1,61 +1,64 @@
 package indirect;
 
-use 5.008001;
+use 5.008_001;
 
 use strict;
 use warnings;
 
 =head1 NAME
 
-indirect - Lexically warn about using the indirect object syntax.
+indirect - Lexically warn about using the indirect method call syntax.
 
 =head1 VERSION
 
-Version 0.25
+Version 0.36
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.25';
+ $VERSION = '0.36';
 }
 
 =head1 SYNOPSIS
 
-    # In a script
-    no indirect;
+In a script :
+
+    no indirect;               # lexically enables the pragma
     my $x = new Apple 1, 2, 3; # warns
     {
-     use indirect;
-     my $y = new Pear; # ok
+     use indirect;     # lexically disables the pragma
+     my $y = new Pear; # legit, does not warn
      {
+      # lexically specify an hook called for each indirect construct
       no indirect hook => sub {
        die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]"
       };
-      # croaks 'You really wanted Pineapple->new at blurp.pm:13'
-      my $z = new Pineapple 'fresh';
+      my $z = new Pineapple 'fresh'; # croaks 'You really wanted...'
      }
     }
-    try { ... }; # warns
+    try { ... }; # warns if try() hasn't been declared in this package
 
-    no indirect ':fatal';    # or 'FATAL', or ':Fatal' ...
+    no indirect 'fatal';     # or ':fatal', 'FATAL', ':Fatal' ...
     if (defied $foo) { ... } # croaks, note the typo
 
-    # Globally enabled from the command-line
+Global uses :
+
+    # Globally enable the pragma from the command-line
     perl -M-indirect=global -e 'my $x = new Banana;' # warns
 
-    # Or globally enabled each time perl is executed
-    export PERL5OPT="-M-indirect=global"
-    perl -e 'my $y = new Coconut;' # warns
+    # Globally enforce the pragma each time perl is executed
+    export PERL5OPT="-M-indirect=global,fatal"
+    perl -e 'my $y = new Coconut;' # croaks
 
 =head1 DESCRIPTION
 
-When enabled (or disabled as some may prefer to say, since you actually turn it on by calling C<no indirect>), this pragma warns about indirect object syntax constructs that may have slipped into your code.
+When enabled, this pragma warns about indirect method calls that are present in your code.
 
-This syntax is now considered harmful, since its parsing has many quirks and its use is error prone (when C<swoosh> is not defined, C<swoosh $x> actually compiles to C<< $x->swoosh >>).
-In L<http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>, Matt S. Trout gives an example of an indirect construct that can cause a particularly bewildering error.
+The indirect syntax is now considered harmful, since its parsing has many quirks and its use is error prone : when the subroutine C<foo> has not been declared in the current package, C<foo $x> actually compiles to C<< $x->foo >>, and C<< foo { key => 1 } >> to C<< 'key'->foo(1) >>.
+Please refer to the L</REFERENCES> section for a more complete list of reasons for avoiding this construct.
 
-It currently does not warn for core functions (C<print>, C<say>, C<exec> or C<system>).
+This pragma currently does not warn for core functions (C<print>, C<say>, C<exec> or C<system>).
 This may change in the future, or may be added as optional features that would be enabled by passing options to C<unimport>.
 
 This module is B<not> a source filter.
@@ -75,7 +78,14 @@ BEGIN {
 
 =head1 METHODS
 
-=head2 C<< unimport [ 'global', hook => $hook | 'fatal' ] >>
+=head2 C<unimport>
+
+    no indirect;
+    no indirect 'fatal';
+    no indirect hook => sub { my ($obj, $name, $file, $line) = @_; ... };
+    no indirect 'global';
+    no indirect 'global, 'fatal';
+    no indirect 'global', hook => sub { ... };
 
 Magically called when C<no indirect @opts> is encountered.
 Turns the module on.
@@ -85,16 +95,20 @@ The policy to apply depends on what is first found in C<@opts> :
 
 =item *
 
-If it is a string that matches C</^:?fatal$/i>, the compilation will croak on the first indirect syntax met.
+If it is a string that matches C</^:?fatal$/i>, the compilation will croak when the first indirect method call is found.
+
+This option is mutually exclusive with the C<'hook'> option.
 
 =item *
 
 If the key/value pair C<< hook => $hook >> comes first, C<$hook> will be called for each error with a string representation of the object as C<$_[0]>, the method name as C<$_[1]>, the current file as C<$_[2]> and the line number as C<$_[3]>.
 If and only if the object is actually a block, C<$_[0]> is assured to start by C<'{'>.
 
+This option is mutually exclusive with the C<'fatal'> option.
+
 =item *
 
-If none of C<fatal> and C<hook> are specified, 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 method call.
 
 =item *
 
@@ -121,24 +135,32 @@ Note that if another policy is installed by a C<no indirect> statement further i
 
 =cut
 
+sub _no_hook_and_fatal {
+ require Carp;
+ Carp::croak("The 'fatal' and 'hook' options are mutually exclusive");
+}
+
 sub unimport {
  shift;
 
- my $hook;
- my $global;
+ my ($global, $fatal, $hook);
+
  while (@_) {
   my $arg = shift;
   if ($arg eq 'hook') {
-   last if $hook;
+   _no_hook_and_fatal() if $fatal;
    $hook = shift;
   } elsif ($arg =~ /^:?fatal$/i) {
-   last if $hook;
-   $hook = sub { die msg(@_) };
+   _no_hook_and_fatal() if defined $hook;
+   $fatal = 1;
   } elsif ($arg =~ /^:?global$/i) {
    $global = 1;
   }
  }
- $hook = sub { warn msg(@_) } unless defined $hook;
+
+ unless (defined $hook) {
+  $hook = $fatal ? sub { die msg(@_) } : sub { warn msg(@_) };
+ }
 
  $^H |= 0x00020000;
  if ($global) {
@@ -153,6 +175,8 @@ sub unimport {
 
 =head2 C<import>
 
+    use indirect;
+
 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).
@@ -168,9 +192,11 @@ sub import {
 
 =head1 FUNCTIONS
 
-=head2 C<msg $object, $method, $file, $line>
+=head2 C<msg>
+
+    my $msg = msg($object, $method, $file, $line);
 
-Returns the default error message generated by C<indirect> when an invalid construct is reported.
+Returns the default error message that C<indirect> generates when an indirect method call is reported.
 
 =cut
 
@@ -197,11 +223,11 @@ This will always be true except on Windows where it's false for perl 5.10.0 and
 
 =head2 C<Indirect call of method "%s" on object "%s" at %s line %d.>
 
-The default warning/exception message thrown when an indirect call on an object is found.
+The default warning/exception message thrown when an indirect method call on an object is found.
 
 =head2 C<Indirect call of method "%s" on a block at %s line %d.>
 
-The default warning/exception message thrown when an indirect call on a block is found.
+The default warning/exception message thrown when an indirect method call on a block is found.
 
 =head1 ENVIRONMENT
 
@@ -218,7 +244,7 @@ If you want to re-enable the pragma later, you also need to reload it by deletin
 
 The implementation was tweaked to work around several limitations of vanilla C<perl> pragmas : it's thread safe, and does not suffer from a C<perl 5.8.x-5.10.0> bug that causes all pragmas to propagate into C<require>d scopes.
 
-Before C<perl> 5.12, C<meth $obj> (no semicolon) at the end of a file is not seen as an indirect object syntax, although it is as soon as there is another token before the end (as in C<meth $obj;> or C<meth $obj 1>).
+Before C<perl> 5.12, C<meth $obj> (no semicolon) at the end of a file is not seen as an indirect method call, although it is as soon as there is another token before the end (as in C<meth $obj;> or C<meth $obj 1>).
 If you use C<perl> 5.12 or greater, those constructs are correctly reported.
 
 With 5.8 perls, the pragma does not propagate into C<eval STRING>.
@@ -227,6 +253,26 @@ This is due to a shortcoming in the way perl handles the hints hash, which is ad
 The search for indirect method calls happens before constant folding.
 Hence C<my $x = new Class if 0> will be caught.
 
+=head1 REFERENCES
+
+Numerous articles have been written about the quirks of the indirect object construct :
+
+=over 4
+
+=item *
+
+L<http://markmail.org/message/o7d5sxnydya7bwvv> : B<Far More Than Everything You've Ever Wanted to Know about the Indirect Object syntax>, Tom Christiansen, 1998-01-28.
+
+This historical post to the C<perl5-porters> mailing list raised awareness about the perils of this syntax.
+
+=item *
+
+L<http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal> : B<Indirect but still fatal>, Matt S. Trout, 2009-07-29.
+
+In this blog post, the author gives an example of an undesirable indirect method call on a block that causes a particularly bewildering error.
+
+=back
+
 =head1 DEPENDENCIES
 
 L<perl> 5.8.1.
@@ -234,7 +280,7 @@ L<perl> 5.8.1.
 A C compiler.
 This module may happen to build with a C++ compiler as well, but don't rely on it, as no guarantee is made in this regard.
 
-L<XSLoader> (standard since perl 5.006).
+L<Carp> (standard since perl 5), L<XSLoader> (since perl 5.6.0).
 
 =head1 AUTHOR
 
@@ -253,8 +299,6 @@ You can find documentation for this module with the perldoc command.
 
     perldoc indirect
 
-Tests code coverage report is available at L<http://www.profvince.com/perl/cover/indirect>.
-
 =head1 ACKNOWLEDGEMENTS
 
 Bram, for motivation and advices.
@@ -263,7 +307,7 @@ Andrew Main and Florian Ragwitz, for testing on real-life code and reporting iss
 
 =head1 COPYRIGHT & LICENSE
 
-Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
+Copyright 2008,2009,2010,2011,2012,2013,2014,2015,2016 Vincent Pit, all rights reserved.
 
 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.