README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.22
   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     "meth $obj" (no semicolon) at the end of a file won't be seen as an
 112     indirect object syntax, although it will as soon as there is another
 113     token before the end (as in "meth $obj;" or "meth $obj 1").
 114
 115     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 116     is due to a shortcoming in the way perl handles the hints hash, which is
 117     addressed in perl 5.10.
 118
 119     The search for indirect method calls happens before constant folding.
 120     Hence "my $x = new Class if 0" will be caught.
 121
 122 DEPENDENCIES
 123     perl 5.8.1.
 124
 125     XSLoader (standard since perl 5.006).
 126
 127 AUTHOR
 128     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 129
 130     You can contact me by mail or on "irc.perl.org" (vincent).
 131
 132 BUGS
 133     Please report any bugs or feature requests to "bug-indirect at
 134     rt.cpan.org", or through the web interface at
 135     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 136     notified, and then you'll automatically be notified of progress on your
 137     bug as I make changes.
 138
 139 SUPPORT
 140     You can find documentation for this module with the perldoc command.
 141
 142         perldoc indirect
 143
 144     Tests code coverage report is available at
 145     <http://www.profvince.com/perl/cover/indirect>.
 146
 147 ACKNOWLEDGEMENTS
 148     Bram, for motivation and advices.
 149
 150     Andrew Main and Florian Ragwitz, for testing on real-life code and
 151     reporting issues.
 152
 153 COPYRIGHT & LICENSE
 154     Copyright 2008,2009,2010 Vincent Pit, all rights reserved.
 155
 156     This program is free software; you can redistribute it and/or modify it
 157     under the same terms as Perl itself.
 158