README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.15
   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         no indirect ':fatal';
  20         if (defied $foo) { ... } # croaks, note the typo
  21
  22         # From the command-line
  23         perl -M-indirect -e 'my $x = new Banana;' # warns
  24
  25         # Or each time perl is ran
  26         export PERL5OPT="-M-indirect"
  27         perl -e 'my $y = new Coconut;' # warns
  28
  29 DESCRIPTION
  30     When enabled (or disabled as some may prefer to say, since you actually
  31     turn it on by calling "no indirect"), this pragma warns about indirect
  32     object syntax constructs that may have slipped into your code. This
  33     syntax is now considered harmful, since its parsing has many quirks and
  34     its use is error prone (when "swoosh" isn't defined, "swoosh $x"
  35     actually compiles to "$x->swoosh").
  36
  37     It currently does not warn when the object is enclosed between braces
  38     (like "meth { $obj } @args") or for core functions ("print" or "say").
  39     This may change in the future, or may be added as optional features that
  40     would be enabled by passing options to "unimport".
  41
  42     This module is not a source filter.
  43
  44 METHODS
  45   "unimport [ hook => $hook | ':fatal' ]"
  46     Magically called when "no indirect @opts" is encountered. Turns the
  47     module on. The policy to apply depends on what is first found in @opts :
  48
  49     *   If it's the string ':fatal', the compilation will croak on the first
  50         indirect syntax met.
  51
  52     *   If the key/value pair "hook => $hook" comes first, $hook will be
  53         called for each error with the object name as $_[0], the method name
  54         as $_[1], the current file as $_[2] and the line number as $_[3].
  55
  56     *   Otherwise, a warning will be emitted for each indirect construct.
  57
  58   "import"
  59     Magically called at each "use indirect". Turns the module off.
  60
  61 CONSTANTS
  62   "I_THREADSAFE"
  63     True iff the module could have been built with thread-safety features
  64     enabled.
  65
  66 CAVEATS
  67     The implementation was tweaked to work around several limitations of
  68     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
  69     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
  70     "require"d scopes.
  71
  72     "meth $obj" (no semicolon) at the end of a file won't be seen as an
  73     indirect object syntax, although it will as soon as there is another
  74     token before the end (as in "meth $obj;" or "meth $obj 1").
  75
  76     With 5.8 perls, the pragma does not propagate into "eval STRING". This
  77     is due to a shortcoming in the way perl handles the hints hash, which is
  78     addressed in perl 5.10.
  79
  80 DEPENDENCIES
  81     perl 5.8.
  82
  83     XSLoader (standard since perl 5.006).
  84
  85 AUTHOR
  86     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
  87
  88     You can contact me by mail or on "irc.perl.org" (vincent).
  89
  90 BUGS
  91     Please report any bugs or feature requests to "bug-indirect at
  92     rt.cpan.org", or through the web interface at
  93     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
  94     notified, and then you'll automatically be notified of progress on your
  95     bug as I make changes.
  96
  97 SUPPORT
  98     You can find documentation for this module with the perldoc command.
  99
 100         perldoc indirect
 101
 102     Tests code coverage report is available at
 103     <http://www.profvince.com/perl/cover/indirect>.
 104
 105 ACKNOWLEDGEMENTS
 106     Bram, for motivation and advices.
 107
 108 COPYRIGHT & LICENSE
 109     Copyright 2008-2009 Vincent Pit, all rights reserved.
 110
 111     This program is free software; you can redistribute it and/or modify it
 112     under the same terms as Perl itself.
 113