| 1 |
NAME |
| 2 |
indirect - Lexically warn about using the indirect method call syntax. |
| 3 |
|
| 4 |
VERSION |
| 5 |
Version 0.39 |
| 6 |
|
| 7 |
SYNOPSIS |
| 8 |
In a script : |
| 9 |
|
| 10 |
no indirect; # lexically enables the pragma |
| 11 |
my $x = new Apple 1, 2, 3; # warns |
| 12 |
{ |
| 13 |
use indirect; # lexically disables the pragma |
| 14 |
my $y = new Pear; # legit, does not warn |
| 15 |
{ |
| 16 |
# lexically specify an hook called for each indirect construct |
| 17 |
no indirect hook => sub { |
| 18 |
die "You really wanted $_[0]\->$_[1] at $_[2]:$_[3]" |
| 19 |
}; |
| 20 |
my $z = new Pineapple 'fresh'; # croaks 'You really wanted...' |
| 21 |
} |
| 22 |
} |
| 23 |
try { ... }; # warns if try() hasn't been declared in this package |
| 24 |
|
| 25 |
no indirect 'fatal'; # or ':fatal', 'FATAL', ':Fatal' ... |
| 26 |
if (defied $foo) { ... } # croaks, note the typo |
| 27 |
|
| 28 |
Global uses : |
| 29 |
|
| 30 |
# Globally enable the pragma from the command-line |
| 31 |
perl -M-indirect=global -e 'my $x = new Banana;' # warns |
| 32 |
|
| 33 |
# Globally enforce the pragma each time perl is executed |
| 34 |
export PERL5OPT="-M-indirect=global,fatal" |
| 35 |
perl -e 'my $y = new Coconut;' # croaks |
| 36 |
|
| 37 |
DESCRIPTION |
| 38 |
When enabled, this pragma warns about indirect method calls that are |
| 39 |
present in your code. |
| 40 |
|
| 41 |
The indirect syntax is now considered harmful, since its parsing has |
| 42 |
many quirks and its use is error prone : when the subroutine "foo" has |
| 43 |
not been declared in the current package, "foo $x" actually compiles to |
| 44 |
"$x->foo", and "foo { key => 1 }" to "'key'->foo(1)". Please refer to |
| 45 |
the "REFERENCES" section for a more complete list of reasons for |
| 46 |
avoiding this construct. |
| 47 |
|
| 48 |
This pragma currently does not warn for core functions ("print", "say", |
| 49 |
"exec" or "system"). This may change in the future, or may be added as |
| 50 |
optional features that would be enabled by passing options to |
| 51 |
"unimport". |
| 52 |
|
| 53 |
This module is not a source filter. |
| 54 |
|
| 55 |
METHODS |
| 56 |
"unimport" |
| 57 |
no indirect; |
| 58 |
no indirect 'fatal'; |
| 59 |
no indirect hook => sub { my ($obj, $name, $file, $line) = @_; ... }; |
| 60 |
no indirect 'global'; |
| 61 |
no indirect 'global, 'fatal'; |
| 62 |
no indirect 'global', hook => sub { ... }; |
| 63 |
|
| 64 |
Magically called when "no indirect @opts" is encountered. Turns the |
| 65 |
module on. The policy to apply depends on what is first found in @opts : |
| 66 |
|
| 67 |
* If it is a string that matches "/^:?fatal$/i", the compilation will |
| 68 |
croak when the first indirect method call is found. |
| 69 |
|
| 70 |
This option is mutually exclusive with the 'hook' option. |
| 71 |
|
| 72 |
* If the key/value pair "hook => $hook" comes first, $hook will be |
| 73 |
called for each error with a string representation of the object as |
| 74 |
$_[0], the method name as $_[1], the current file as $_[2] and the |
| 75 |
line number as $_[3]. If and only if the object is actually a block, |
| 76 |
$_[0] is assured to start by '{'. |
| 77 |
|
| 78 |
This option is mutually exclusive with the 'fatal' option. |
| 79 |
|
| 80 |
* If none of "fatal" and "hook" are specified, a warning will be |
| 81 |
emitted for each indirect method call. |
| 82 |
|
| 83 |
* If @opts contains a string that matches "/^:?global$/i", the pragma |
| 84 |
will be globally enabled for all code compiled after the current "no |
| 85 |
indirect" statement, except for code that is in the lexical scope of |
| 86 |
"use indirect". This option may come indifferently before or after |
| 87 |
the "fatal" or "hook" options, in the case they are also passed to |
| 88 |
"unimport". |
| 89 |
|
| 90 |
The global policy applied is the one resulting of the "fatal" or |
| 91 |
"hook" options, thus defaults to a warning when none of those are |
| 92 |
specified : |
| 93 |
|
| 94 |
no indirect 'global'; # warn for any indirect call |
| 95 |
no indirect qw<global fatal>; # die on any indirect call |
| 96 |
no indirect 'global', hook => \&hook # custom global action |
| 97 |
|
| 98 |
Note that if another policy is installed by a "no indirect" |
| 99 |
statement further in the code, it will overrule the global policy : |
| 100 |
|
| 101 |
no indirect 'global'; # warn globally |
| 102 |
{ |
| 103 |
no indirect 'fatal'; # throw exceptions for this lexical scope |
| 104 |
... |
| 105 |
require Some::Module; # the global policy will apply for the |
| 106 |
# compilation phase of this module |
| 107 |
} |
| 108 |
|
| 109 |
"import" |
| 110 |
use indirect; |
| 111 |
|
| 112 |
Magically called at each "use indirect". Turns the module off. |
| 113 |
|
| 114 |
As explained in "unimport"'s description, an "use indirect" statement |
| 115 |
will lexically override a global policy previously installed by "no |
| 116 |
indirect 'global', ..." (if there's one). |
| 117 |
|
| 118 |
FUNCTIONS |
| 119 |
"msg" |
| 120 |
my $msg = msg($object, $method, $file, $line); |
| 121 |
|
| 122 |
Returns the default error message that "indirect" generates when an |
| 123 |
indirect method call is reported. |
| 124 |
|
| 125 |
CONSTANTS |
| 126 |
"I_THREADSAFE" |
| 127 |
True iff the module could have been built with thread-safety features |
| 128 |
enabled. |
| 129 |
|
| 130 |
"I_FORKSAFE" |
| 131 |
True iff this module could have been built with fork-safety features |
| 132 |
enabled. This will always be true except on Windows where it's false for |
| 133 |
perl 5.10.0 and below . |
| 134 |
|
| 135 |
DIAGNOSTICS |
| 136 |
"Indirect call of method "%s" on object "%s" at %s line %d." |
| 137 |
The default warning/exception message thrown when an indirect method |
| 138 |
call on an object is found. |
| 139 |
|
| 140 |
"Indirect call of method "%s" on a block at %s line %d." |
| 141 |
The default warning/exception message thrown when an indirect method |
| 142 |
call on a block is found. |
| 143 |
|
| 144 |
ENVIRONMENT |
| 145 |
"PERL_INDIRECT_PM_DISABLE" |
| 146 |
If this environment variable is set to true when the pragma is used for |
| 147 |
the first time, the XS code won't be loaded and, although the 'indirect' |
| 148 |
lexical hint will be set to true in the scope of use, the pragma itself |
| 149 |
won't do anything. In this case, the pragma will always be considered to |
| 150 |
be thread-safe, and as such "I_THREADSAFE" will be true. This is useful |
| 151 |
for disabling "indirect" in production environments. |
| 152 |
|
| 153 |
Note that clearing this variable after "indirect" was loaded has no |
| 154 |
effect. If you want to re-enable the pragma later, you also need to |
| 155 |
reload it by deleting the 'indirect.pm' entry from %INC. |
| 156 |
|
| 157 |
CAVEATS |
| 158 |
The implementation was tweaked to work around several limitations of |
| 159 |
vanilla "perl" pragmas : it's thread safe, and does not suffer from a |
| 160 |
"perl 5.8.x-5.10.0" bug that causes all pragmas to propagate into |
| 161 |
"require"d scopes. |
| 162 |
|
| 163 |
Before "perl" 5.12, "meth $obj" (no semicolon) at the end of a file is |
| 164 |
not seen as an indirect method call, although it is as soon as there is |
| 165 |
another token before the end (as in "meth $obj;" or "meth $obj 1"). If |
| 166 |
you use "perl" 5.12 or greater, those constructs are correctly reported. |
| 167 |
|
| 168 |
With 5.8 perls, the pragma does not propagate into "eval STRING". This |
| 169 |
is due to a shortcoming in the way perl handles the hints hash, which is |
| 170 |
addressed in perl 5.10. |
| 171 |
|
| 172 |
The search for indirect method calls happens before constant folding. |
| 173 |
Hence "my $x = new Class if 0" will be caught. |
| 174 |
|
| 175 |
REFERENCES |
| 176 |
Numerous articles have been written about the quirks of the indirect |
| 177 |
object construct : |
| 178 |
|
| 179 |
* <http://markmail.org/message/o7d5sxnydya7bwvv> : Far More Than |
| 180 |
Everything You've Ever Wanted to Know about the Indirect Object |
| 181 |
syntax, Tom Christiansen, 1998-01-28. |
| 182 |
|
| 183 |
This historical post to the "perl5-porters" mailing list raised |
| 184 |
awareness about the perils of this syntax. |
| 185 |
|
| 186 |
* <http://www.shadowcat.co.uk/blog/matt-s-trout/indirect-but-still-fat |
| 187 |
al> : Indirect but still fatal, Matt S. Trout, 2009-07-29. |
| 188 |
|
| 189 |
In this blog post, the author gives an example of an undesirable |
| 190 |
indirect method call on a block that causes a particularly |
| 191 |
bewildering error. |
| 192 |
|
| 193 |
DEPENDENCIES |
| 194 |
perl 5.8.1. |
| 195 |
|
| 196 |
A C compiler. This module may happen to build with a C++ compiler as |
| 197 |
well, but don't rely on it, as no guarantee is made in this regard. |
| 198 |
|
| 199 |
Carp (standard since perl 5), XSLoader (since perl 5.6.0). |
| 200 |
|
| 201 |
AUTHOR |
| 202 |
Vincent Pit "<[email protected]>". |
| 203 |
|
| 204 |
You can contact me by mail or on "irc.perl.org" (vincent). |
| 205 |
|
| 206 |
BUGS |
| 207 |
Please report any bugs or feature requests to "bug-indirect at |
| 208 |
rt.cpan.org", or through the web interface at |
| 209 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=indirect>. I will be |
| 210 |
notified, and then you'll automatically be notified of progress on your |
| 211 |
bug as I make changes. |
| 212 |
|
| 213 |
SUPPORT |
| 214 |
You can find documentation for this module with the perldoc command. |
| 215 |
|
| 216 |
perldoc indirect |
| 217 |
|
| 218 |
ACKNOWLEDGEMENTS |
| 219 |
Bram, for motivation and advices. |
| 220 |
|
| 221 |
Andrew Main and Florian Ragwitz, for testing on real-life code and |
| 222 |
reporting issues. |
| 223 |
|
| 224 |
COPYRIGHT & LICENSE |
| 225 |
Copyright 2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2019 Vincent |
| 226 |
Pit, all rights reserved. |
| 227 |
|
| 228 |
This program is free software; you can redistribute it and/or modify it |
| 229 |
under the same terms as Perl itself. |
| 230 |
|