README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.18
   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 DIAGNOSTICS
  75   "Indirect call of method "%s" on object "%s" at %s line %d."
  76     The default warning/exception message thrown when an indirect call on an
  77     object is found.
  78
  79   "Indirect call of method "%s" on a block at %s line %d."
  80     The default warning/exception message thrown when an indirect call on a
  81     block is found.
  82
  83 ENVIRONMENT
  84   "PERL_INDIRECT_PM_DISABLE"
  85     If this environment variable is set to true when the pragma is used for
  86     the first time, the XS code won't be loaded and, although the 'indirect'
  87     lexical hint will be set to true in the scope of use, the pragma itself
  88     won't do anything. This is useful for disabling "indirect" in production
  89     environments.
  90
  91     Note that clearing this variable after "indirect" was loaded has no
  92     effect. If you want to reenable the pragma later, you also need to
  93     reload it by deleting the 'indirect.pm' entry from %INC.
  94
  95 CAVEATS
  96     The implementation was tweaked to work around several limitations of
  97     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
  98     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
  99     "require"d scopes.
 100
 101     "meth $obj" (no semicolon) at the end of a file won't be seen as an
 102     indirect object syntax, although it will as soon as there is another
 103     token before the end (as in "meth $obj;" or "meth $obj 1").
 104
 105     With 5.8 perls, the pragma does not propagate into "eval STRING". This
 106     is due to a shortcoming in the way perl handles the hints hash, which is
 107     addressed in perl 5.10.
 108
 109     The search for indirect method calls happens before constant folding.
 110     Hence "my $x = new Class if 0" will be caught.
 111
 112 DEPENDENCIES
 113     perl 5.8.
 114
 115     XSLoader (standard since perl 5.006).
 116
 117 AUTHOR
 118     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 119
 120     You can contact me by mail or on "irc.perl.org" (vincent).
 121
 122 BUGS
 123     Please report any bugs or feature requests to "bug-indirect at
 124     rt.cpan.org", or through the web interface at
 125     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 126     notified, and then you'll automatically be notified of progress on your
 127     bug as I make changes.
 128
 129 SUPPORT
 130     You can find documentation for this module with the perldoc command.
 131
 132         perldoc indirect
 133
 134     Tests code coverage report is available at
 135     <http://www.profvince.com/perl/cover/indirect>.
 136
 137 ACKNOWLEDGEMENTS
 138     Bram, for motivation and advices.
 139
 140     Andrew Main and Florian Ragwitz, for testing on real-life code and
 141     reporting issues.
 142
 143 COPYRIGHT & LICENSE
 144     Copyright 2008-2009 Vincent Pit, all rights reserved.
 145
 146     This program is free software; you can redistribute it and/or modify it
 147     under the same terms as Perl itself.
 148