X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Findirect.git;a=blobdiff_plain;f=README;h=3807d3b2cefc53d725e9cd962961d551a8586b98;hp=b16dba1f1d2b1ad7a1aa970966736c5218645dd0;hb=faa0984a60b4134d0556ed7e6225bf83ddfb5474;hpb=1e73136219e28f80e67999f68c801588afb512a9 diff --git a/README b/README index b16dba1..3807d3b 100644 --- a/README +++ b/README @@ -1,53 +1,190 @@ NAME - indirect - Lexically warn about using the indirect object syntax. + indirect - Lexically warn about using the indirect method call syntax. VERSION - Version 0.03 + 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, 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 + , + 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" - Magically called when "no indirect @args" is encountered. Turns the - module on. If @opts contains ':fatal', the module will croak on the - first indirect syntax met. + "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. 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; # 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" + use indirect; + Magically called at each "use indirect". Turns the module off. + 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 + 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.9.4. + perl 5.8.1. - XSLoader (standard since perl 5.006). + 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. - Tests require IPC::Cmd (standard since 5.9.5). + Carp (standard since perl 5), XSLoader (since perl 5.006). AUTHOR Vincent Pit, "", . - You can contact me by mail or on #perl @ FreeNode (vincent or - Prof_Vince). + You can contact me by mail or on "irc.perl.org" (vincent). BUGS Please report any bugs or feature requests to "bug-indirect at @@ -61,11 +198,18 @@ SUPPORT perldoc indirect + Tests code coverage report is available at + . + 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.