NAME
- indirect - Lexically warn about using the indirect object syntax.
+ indirect - Lexically warn about using the indirect method call syntax.
VERSION
- Version 0.09_01
+ Version 0.30
SYNOPSIS
- no indirect;
+ In a script :
+
+ no indirect; # lexically enables the pragma
my $x = new Apple 1, 2, 3; # warns
{
- use indirect;
- my $y = new Pear; # ok
+ use indirect; # lexically disables the pragma
+ my $y = new Pear; # legit, does not warn
+ {
+ # lexically specify an hook called for each indirect construct
+ no indirect hook => sub {
+ die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]"
+ };
+ my $z = new Pineapple 'fresh'; # croaks 'You really wanted...'
+ }
}
- no indirect ':fatal';
+ try { ... }; # warns if try() hasn't been declared in this package
+
+ no indirect 'fatal'; # or ':fatal', 'FATAL', ':Fatal' ...
if (defied $foo) { ... } # croaks, note the typo
+ Global uses :
+
+ # Globally enable the pragma from the command-line
+ perl -M-indirect=global -e 'my $x = new Banana;' # warns
+
+ # Globally enforce the pragma each time perl is executed
+ export PERL5OPT="-M-indirect=global,fatal"
+ perl -e 'my $y = new Coconut;' # croaks
+
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").
-
- 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".
+ When enabled, this pragma warns about indirect method calls that are
+ present in your code.
+
+ The indirect syntax is now considered harmful, since its parsing has
+ many quirks and its use is error prone : when the subroutine "foo" has
+ not been declared in the current package, "foo $x" actually compiles to
+ "$x->foo", and "foo { key => 1 }" to "'key'->foo(1)". In
+ <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fatal>,
+ Matt S. Trout gives an example of an undesirable indirect method call on
+ a block that can cause a particularly bewildering error.
+
+ This pragma 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"
+ no indirect;
+ no indirect 'fatal';
+ no indirect hook => sub { my ($obj, $name, $file, $line) = @_; ... };
+ no indirect 'global';
+ no indirect 'global, 'fatal';
+ no indirect 'global', hook => sub { ... };
+
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 when the first indirect method call is found.
+
+ This option is mutually exclusive with the 'hook' option.
+
+ * 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 '{'.
+
+ This option is mutually exclusive with the 'fatal' option.
+
+ * If none of "fatal" and "hook" are specified, a warning will be
+ emitted for each indirect method call.
+
+ * If @opts contains a string that matches "/^:?global$/i", the pragma
+ will be globally enabled for all code compiled after the current "no
+ indirect" statement, except for code that is in the lexical scope of
+ "use indirect". This option may come indifferently before or after
+ the "fatal" or "hook" options, in the case they are also passed to
+ "unimport".
+
+ The global policy applied is the one resulting of the "fatal" or
+ "hook" options, thus defaults to a warning when none of those are
+ specified :
+
+ no indirect 'global'; # warn for any indirect call
+ no indirect qw<global fatal>; # die on any indirect call
+ no indirect 'global', hook => \&hook # custom global action
+
+ Note that if another policy is installed by a "no indirect"
+ statement further in the code, it will overrule the global policy :
+
+ no indirect 'global'; # warn globally
+ {
+ no indirect 'fatal'; # throw exceptions for this lexical scope
+ ...
+ require Some::Module; # the global policy will apply for the
+ # compilation phase of this module
+ }
"import"
- Magically called at each "use indirect". Turns the module off.
+ use indirect;
-DEPENDENCIES
- perl 5.8.
+ Magically called at each "use indirect". Turns the module off.
- XSLoader (standard since perl 5.006).
+ As explained in "unimport"'s description, an "use indirect" statement
+ will lexically override a global policy previously installed by "no
+ indirect 'global', ..." (if there's one).
+
+FUNCTIONS
+ "msg"
+ my $msg = msg($object, $method, $file, $line);
+
+ Returns the default error message that "indirect" generates when an
+ indirect method call 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 method
+ 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 method
+ 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
- "meth $obj" (no semicolon) at the end of a file won't be seen as an
- indirect object syntax, although it will as soon as there is another
- token before the end (as in "meth $obj;" or "meth $obj 1").
+ 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 method call, 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.8.1.
+
+ A C compiler. This module may happen to build with a C++ compiler as
+ well, but don't rely on it, as no guarantee is made in this regard.
+
+ Carp (standard since perl 5), XSLoader (since perl 5.006).
+
AUTHOR
Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
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,2011,2012,2013 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