README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.17
   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 CAVEATS
  84     The implementation was tweaked to work around several limitations of
  85     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
  86     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
  87     "require"d scopes.
  88
  89     "meth $obj" (no semicolon) at the end of a file won't be seen as an
  90     indirect object syntax, although it will as soon as there is another
  91     token before the end (as in "meth $obj;" or "meth $obj 1").
  92
  93     With 5.8 perls, the pragma does not propagate into "eval STRING". This
  94     is due to a shortcoming in the way perl handles the hints hash, which is
  95     addressed in perl 5.10.
  96
  97     The search for indirect method calls happens before constant folding.
  98     Hence "my $x = new Class if 0" will be caught.
  99
 100 DEPENDENCIES
 101     perl 5.8.
 102
 103     XSLoader (standard since perl 5.006).
 104
 105 AUTHOR
 106     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 107
 108     You can contact me by mail or on "irc.perl.org" (vincent).
 109
 110 BUGS
 111     Please report any bugs or feature requests to "bug-indirect at
 112     rt.cpan.org", or through the web interface at
 113     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 114     notified, and then you'll automatically be notified of progress on your
 115     bug as I make changes.
 116
 117 SUPPORT
 118     You can find documentation for this module with the perldoc command.
 119
 120         perldoc indirect
 121
 122     Tests code coverage report is available at
 123     <http://www.profvince.com/perl/cover/indirect>.
 124
 125 ACKNOWLEDGEMENTS
 126     Bram, for motivation and advices.
 127
 128     Andrew Main and Florian Ragwitz, for testing on real-life code and
 129     reporting issues.
 130
 131 COPYRIGHT & LICENSE
 132     Copyright 2008-2009 Vincent Pit, all rights reserved.
 133
 134     This program is free software; you can redistribute it and/or modify it
 135     under the same terms as Perl itself.
 136