README

   1 NAME
   2     indirect - Lexically warn about using the indirect object syntax.
   3
   4 VERSION
   5     Version 0.14
   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]" };
  16           my $z = new Pineapple 'fresh'; # croaks 'You really wanted Pineapple->new'
  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 when thread-safety features.
  64
  65 CAVEATS
  66     The implementation was tweaked to work around several limitations of
  67     vanilla "perl" pragmas : it's thread safe, and doesn't suffer from a
  68     "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
  69     "require"d scopes.
  70
  71     "meth $obj" (no semicolon) at the end of a file won't be seen as an
  72     indirect object syntax, although it will as soon as there is another
  73     token before the end (as in "meth $obj;" or "meth $obj 1").
  74
  75     With 5.8 perls, the pragma does not propagate into "eval STRING". This
  76     is due to a shortcoming in the way perl handles the hints hash, which is
  77     addressed in perl 5.10.
  78
  79 DEPENDENCIES
  80     perl 5.8.
  81
  82     XSLoader (standard since perl 5.006).
  83
  84 AUTHOR
  85     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
  86
  87     You can contact me by mail or on "irc.perl.org" (vincent).
  88
  89 BUGS
  90     Please report any bugs or feature requests to "bug-indirect at
  91     rt.cpan.org", or through the web interface at
  92     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be
  93     notified, and then you'll automatically be notified of progress on your
  94     bug as I make changes.
  95
  96 SUPPORT
  97     You can find documentation for this module with the perldoc command.
  98
  99         perldoc indirect
 100
 101     Tests code coverage report is available at
 102     <http://www.profvince.com/perl/cover/indirect>.
 103
 104 ACKNOWLEDGEMENTS
 105     Bram, for motivation and advices.
 106
 107 COPYRIGHT & LICENSE
 108     Copyright 2008-2009 Vincent Pit, all rights reserved.
 109
 110     This program is free software; you can redistribute it and/or modify it
 111     under the same terms as Perl itself.
 112