README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.25
   6
   7 SYNOPSIS
   8         # In a script
   9         no indirect;
  10         my $x = new Apple 1, 2, 3; # warns
  11         {
  12          use indirect;
  13          my $y = new Pear; # ok
  14          {
  15           no indirect hook => sub { die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]" };
  16           my $z = new Pineapple 'fresh'; # croaks 'You really wanted Pineapple->new at blurp.pm:13'
  17          }
  18         }
  19         try { ... }; # warns
  20
  21         no indirect ':fatal';    # or 'FATAL', or ':Fatal' ...
  22         if (defied $foo) { ... } # croaks, note the typo
  23
  24         # From the command-line
  25         perl -M-indirect -e 'my $x = new Banana;' # warns
  26
  27         # Or each time perl is ran
  28         export PERL5OPT="-M-indirect"
  29         perl -e 'my $y = new Coconut;' # warns
  30
  31 DESCRIPTION
  32     When enabled (or disabled as some may prefer to say, since you actually
  33     turn it on by calling "no indirect"), this pragma warns about indirect
  34     object syntax constructs that may have slipped into your code.
  35
  36     This syntax is now considered harmful, since its parsing has many quirks
  37     and its use is error prone (when "swoosh" is not defined, "swoosh $x"
  38     actually compiles to "$x->swoosh"). In
  39     <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>,
  40     Matt S. Trout gives an example of an indirect construct that can cause a
  41     particularly bewildering error.
  42
  43     It currently does not warn for core functions ("print", "say", "exec" or
  44     "system"). This may change in the future, or may be added as optional
  45     features that would be enabled by passing options to "unimport".
  46
  47     This module is not a source filter.
  48
  49 METHODS
  50   "unimport [ hook => $hook | ':fatal', 'FATAL', ... ]"
  51     Magically called when "no indirect @opts" is encountered. Turns the
  52     module on. The policy to apply depends on what is first found in @opts :
  53
  54     *   If it is a string that matches "/^:?fatal$/i", the compilation will
  55         croak on the first indirect syntax met.
  56
  57     *   If the key/value pair "hook => $hook" comes first, $hook will be
  58         called for each error with a string representation of the object as
  59         $_[0], the method name as $_[1], the current file as $_[2] and the
  60         line number as $_[3]. If and only if the object is actually a block,
  61         $_[0] is assured to start by '{'.
  62
  63     *   Otherwise, a warning will be emitted for each indirect construct.
  64
  65   "import"
  66     Magically called at each "use indirect". Turns the module off.
  67
  68 FUNCTIONS
  69   "msg $object, $method, $file, $line"
  70     Returns the default error message generated by "indirect" when an
  71     invalid construct is reported.
  72
  73 CONSTANTS
  74   "I_THREADSAFE"
  75     True iff the module could have been built with thread-safety features
  76     enabled.
  77
  78   "I_FORKSAFE"
  79     True iff this module could have been built with fork-safety features
  80     enabled. This will always be true except on Windows where it's false for
  81     perl 5.10.0 and below .
  82
  83 DIAGNOSTICS
  84   "Indirect call of method "%s" on object "%s" at %s line %d."
  85     The default warning/exception message thrown when an indirect call on an
  86     object is found.
  87
  88   "Indirect call of method "%s" on a block at %s line %d."
  89     The default warning/exception message thrown when an indirect call on a
  90     block is found.
  91
  92 ENVIRONMENT
  93   "PERL_INDIRECT_PM_DISABLE"
  94     If this environment variable is set to true when the pragma is used for
  95     the first time, the XS code won't be loaded and, although the 'indirect'
  96     lexical hint will be set to true in the scope of use, the pragma itself
  97     won't do anything. In this case, the pragma will always be considered to
  98     be thread-safe, and as such "I_THREADSAFE" will be true. This is useful
  99     for disabling "indirect" in production environments.
 100
 101     Note that clearing this variable after "indirect" was loaded has no
 102     effect. If you want to re-enable the pragma later, you also need to
 103     reload it by deleting the 'indirect.pm' entry from %INC.
 104
 105 CAVEATS
 106     The implementation was tweaked to work around several limitations of
 107     vanilla "perl" pragmas : it's thread safe, and does not suffer from a
 108     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
 109     "require"d scopes.
 110
 111     Before "perl" 5.12, "meth $obj" (no semicolon) at the end of a file is
 112     not seen as an indirect object syntax, although it is as soon as there
 113     is another token before the end (as in "meth $obj;" or "meth $obj 1").
 114     If you use "perl" 5.12 or greater, those constructs are correctly
 115     reported.
 116
 117     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 118     is due to a shortcoming in the way perl handles the hints hash, which is
 119     addressed in perl 5.10.
 120
 121     The search for indirect method calls happens before constant folding.
 122     Hence "my $x = new Class if 0" will be caught.
 123
 124 DEPENDENCIES
 125     perl 5.8.1.
 126
 127     A C compiler. This module may happen to build with a C++ compiler as
 128     well, but don't rely on it, as no guarantee is made in this regard.
 129
 130     XSLoader (standard since perl 5.006).
 131
 132 AUTHOR
 133     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 134
 135     You can contact me by mail or on "irc.perl.org" (vincent).
 136
 137 BUGS
 138     Please report any bugs or feature requests to "bug-indirect at
 139     rt.cpan.org", or through the web interface at
 140     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 141     notified, and then you'll automatically be notified of progress on your
 142     bug as I make changes.
 143
 144 SUPPORT
 145     You can find documentation for this module with the perldoc command.
 146
 147         perldoc indirect
 148
 149     Tests code coverage report is available at
 150     <http://www.profvince.com/perl/cover/indirect>.
 151
 152 ACKNOWLEDGEMENTS
 153     Bram, for motivation and advices.
 154
 155     Andrew Main and Florian Ragwitz, for testing on real-life code and
 156     reporting issues.
 157
 158 COPYRIGHT & LICENSE
 159     Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
 160
 161     This program is free software; you can redistribute it and/or modify it
 162     under the same terms as Perl itself.
 163