indirect - Lexically warn about using the indirect object syntax.
VERSION
- Version 0.07_02
+ Version 0.23
SYNOPSIS
+ # In a script
no indirect;
my $x = new Apple 1, 2, 3; # warns
{
use indirect;
my $y = new Pear; # ok
+ {
+ no indirect hook => sub { die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]" };
+ my $z = new Pineapple 'fresh'; # croaks 'You really wanted Pineapple->new at blurp.pm:13'
+ }
}
- no indirect ':fatal';
+ try { ... }; # warns
+
+ no indirect ':fatal'; # or 'FATAL', or ':Fatal' ...
if (defied $foo) { ... } # croaks, note the typo
+ # From the command-line
+ perl -M-indirect -e 'my $x = new Banana;' # warns
+
+ # Or each time perl is ran
+ export PERL5OPT="-M-indirect"
+ perl -e 'my $y = new Coconut;' # warns
+
DESCRIPTION
When enabled (or disabled as some may prefer to say, since you actually
turn it on by calling "no indirect"), this pragma warns about indirect
- object syntax constructs that may have slipped into your code. This
- syntax is now considered harmful, since its parsing has many quirks and
- its use is error prone (when "sub" isn't defined, "sub $x" is actually
- interpreted as "$x->sub").
+ object syntax constructs that may have slipped into your code.
- It currently does not warn when the object is enclosed between braces
- (like "meth { $obj } @args") or for core functions ("print" or "say").
- This may change in the future, or may be added as optional features that
- would be enabled by passing options to "unimport".
+ This syntax is now considered harmful, since its parsing has many quirks
+ and its use is error prone (when "swoosh" is not defined, "swoosh $x"
+ actually compiles to "$x->swoosh"). In
+ <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>,
+ Matt S. Trout gives an example of an indirect construct that can cause a
+ particularly bewildering error.
+
+ It currently does not warn for core functions ("print", "say", "exec" or
+ "system"). This may change in the future, or may be added as optional
+ features that would be enabled by passing options to "unimport".
This module is not a source filter.
METHODS
- "unimport @opts"
+ "unimport [ hook => $hook | ':fatal', 'FATAL', ... ]"
Magically called when "no indirect @opts" is encountered. Turns the
- module on. If @opts contains ':fatal', the module will croak on the
- first indirect syntax met.
+ module on. The policy to apply depends on what is first found in @opts :
+
+ * If it is a string that matches "/^:?fatal$/i", the compilation will
+ croak on the first indirect syntax met.
+
+ * If the key/value pair "hook => $hook" comes first, $hook will be
+ called for each error with a string representation of the object as
+ $_[0], the method name as $_[1], the current file as $_[2] and the
+ line number as $_[3]. If and only if the object is actually a block,
+ $_[0] is assured to start by '{'.
+
+ * Otherwise, a warning will be emitted for each indirect construct.
"import"
Magically called at each "use indirect". Turns the module off.
+FUNCTIONS
+ "msg $object, $method, $file, $line"
+ Returns the default error message generated by "indirect" when an
+ invalid construct is reported.
+
+CONSTANTS
+ "I_THREADSAFE"
+ True iff the module could have been built with thread-safety features
+ enabled.
+
+ "I_FORKSAFE"
+ True iff this module could have been built with fork-safety features
+ enabled. This will always be true except on Windows where it's false for
+ perl 5.10.0 and below .
+
+DIAGNOSTICS
+ "Indirect call of method "%s" on object "%s" at %s line %d."
+ The default warning/exception message thrown when an indirect call on an
+ object is found.
+
+ "Indirect call of method "%s" on a block at %s line %d."
+ The default warning/exception message thrown when an indirect call on a
+ block is found.
+
+ENVIRONMENT
+ "PERL_INDIRECT_PM_DISABLE"
+ If this environment variable is set to true when the pragma is used for
+ the first time, the XS code won't be loaded and, although the 'indirect'
+ lexical hint will be set to true in the scope of use, the pragma itself
+ won't do anything. In this case, the pragma will always be considered to
+ be thread-safe, and as such "I_THREADSAFE" will be true. This is useful
+ for disabling "indirect" in production environments.
+
+ Note that clearing this variable after "indirect" was loaded has no
+ effect. If you want to re-enable the pragma later, you also need to
+ reload it by deleting the 'indirect.pm' entry from %INC.
+
+CAVEATS
+ The implementation was tweaked to work around several limitations of
+ vanilla "perl" pragmas : it's thread safe, and does not suffer from a
+ "perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into
+ "require"d scopes.
+
+ Before "perl" 5.12, "meth $obj" (no semicolon) at the end of a file is
+ not seen as an indirect object syntax, although it is as soon as there
+ is another token before the end (as in "meth $obj;" or "meth $obj 1").
+ If you use "perl" 5.12 or greater, those constructs are correctly
+ reported.
+
+ With 5.8 perls, the pragma does not propagate into "eval STRING". This
+ is due to a shortcoming in the way perl handles the hints hash, which is
+ addressed in perl 5.10.
+
+ The search for indirect method calls happens before constant folding.
+ Hence "my $x = new Class if 0" will be caught.
+
DEPENDENCIES
- perl 5.9.4.
+ perl 5.8.1.
XSLoader (standard since perl 5.006).
ACKNOWLEDGEMENTS
Bram, for motivation and advices.
+ Andrew Main and Florian Ragwitz, for testing on real-life code and
+ reporting issues.
+
COPYRIGHT & LICENSE
- Copyright 2008 Vincent Pit, all rights reserved.
+ Copyright 2008,2009,2010 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
projects / perl / modules / indirect.git / blobdiff