README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.16
   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 DEPENDENCIES
  98     perl 5.8.
  99
 100     XSLoader (standard since perl 5.006).
 101
 102 AUTHOR
 103     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 104
 105     You can contact me by mail or on "irc.perl.org" (vincent).
 106
 107 BUGS
 108     Please report any bugs or feature requests to "bug-indirect at
 109     rt.cpan.org", or through the web interface at
 110     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
 111     notified, and then you'll automatically be notified of progress on your
 112     bug as I make changes.
 113
 114 SUPPORT
 115     You can find documentation for this module with the perldoc command.
 116
 117         perldoc indirect
 118
 119     Tests code coverage report is available at
 120     <http://www.profvince.com/perl/cover/indirect>.
 121
 122 ACKNOWLEDGEMENTS
 123     Bram, for motivation and advices.
 124
 125     Andrew Main and Florian Ragwitz, for testing on real-life code and
 126     reporting issues.
 127
 128 COPYRIGHT & LICENSE
 129     Copyright 2008-2009 Vincent Pit, all rights reserved.
 130
 131     This program is free software; you can redistribute it and/or modify it
 132     under the same terms as Perl itself.
 133