README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.19
   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';
  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. This
  35     syntax is now considered harmful, since its parsing has many quirks and
  36     its use is error prone (when "swoosh" isn't defined, "swoosh $x"
  37     actually compiles to "$x->swoosh").
  38
  39     It currently does not warn for core functions ("print", "say", "exec" or
  40     "system"). This may change in the future, or may be added as optional
  41     features that would be enabled by passing options to "unimport".
  42
  43     This module is not a source filter.
  44
  45 METHODS
  46   "unimport [ hook => $hook | ':fatal' ]"
  47     Magically called when "no indirect @opts" is encountered. Turns the
  48     module on. The policy to apply depends on what is first found in @opts :
  49
  50     *   If it's the string ':fatal', the compilation will croak on the first
  51         indirect syntax met.
  52
  53     *   If the key/value pair "hook => $hook" comes first, $hook will be
  54         called for each error with a string representation of the object as
  55         $_[0], the method name as $_[1], the current file as $_[2] and the
  56         line number as $_[3]. If and only if the object is actually a block,
  57         $_[0] is assured to start by '{'.
  58
  59     *   Otherwise, a warning will be emitted for each indirect construct.
  60
  61   "import"
  62     Magically called at each "use indirect". Turns the module off.
  63
  64 FUNCTIONS
  65   "msg $object, $method, $file, $line"
  66     Returns the default error message generated by "indirect" when an
  67     invalid construct is reported.
  68
  69 CONSTANTS
  70   "I_THREADSAFE"
  71     True iff the module could have been built with thread-safety features
  72     enabled.
  73
  74   "I_FORKSAFE"
  75     True iff this module could have been built with fork-safety features
  76     enabled. This will always be true except on Windows where it's false for
  77     perl 5.10.0 and below .
  78
  79 DIAGNOSTICS
  80   "Indirect call of method "%s" on object "%s" at %s line %d."
  81     The default warning/exception message thrown when an indirect call on an
  82     object is found.
  83
  84   "Indirect call of method "%s" on a block at %s line %d."
  85     The default warning/exception message thrown when an indirect call on a
  86     block is found.
  87
  88 ENVIRONMENT
  89   "PERL_INDIRECT_PM_DISABLE"
  90     If this environment variable is set to true when the pragma is used for
  91     the first time, the XS code won't be loaded and, although the 'indirect'
  92     lexical hint will be set to true in the scope of use, the pragma itself
  93     won't do anything. In this case, the pragma will always be considered to
  94     be thread-safe, and as such "I_THREADSAFE" will be true. This is useful
  95     for disabling "indirect" in production environments.
  96
  97     Note that clearing this variable after "indirect" was loaded has no
  98     effect. If you want to reenable the pragma later, you also need to
  99     reload it by deleting the 'indirect.pm' entry from %INC.
 100
 101 CAVEATS
 102     The implementation was tweaked to work around several limitations of
 103     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
 104     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
 105     "require"d scopes.
 106
 107     "meth $obj" (no semicolon) at the end of a file won't be seen as an
 108     indirect object syntax, although it will as soon as there is another
 109     token before the end (as in "meth $obj;" or "meth $obj 1").
 110
 111     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 112     is due to a shortcoming in the way perl handles the hints hash, which is
 113     addressed in perl 5.10.
 114
 115     The search for indirect method calls happens before constant folding.
 116     Hence "my $x = new Class if 0" will be caught.
 117
 118 DEPENDENCIES
 119     perl 5.8.
 120
 121     XSLoader (standard since perl 5.006).
 122
 123 AUTHOR
 124     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 125
 126     You can contact me by mail or on "irc.perl.org" (vincent).
 127
 128 BUGS
 129     Please report any bugs or feature requests to "bug-indirect at
 130     rt.cpan.org", or through the web interface at
 131     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 132     notified, and then you'll automatically be notified of progress on your
 133     bug as I make changes.
 134
 135 SUPPORT
 136     You can find documentation for this module with the perldoc command.
 137
 138         perldoc indirect
 139
 140     Tests code coverage report is available at
 141     <http://www.profvince.com/perl/cover/indirect>.
 142
 143 ACKNOWLEDGEMENTS
 144     Bram, for motivation and advices.
 145
 146     Andrew Main and Florian Ragwitz, for testing on real-life code and
 147     reporting issues.
 148
 149 COPYRIGHT & LICENSE
 150     Copyright 2008-2009 Vincent Pit, all rights reserved.
 151
 152     This program is free software; you can redistribute it and/or modify it
 153     under the same terms as Perl itself.
 154