X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Findirect.git;a=blobdiff_plain;f=README;h=e1aa30551a21b8d57b5b484bfd0709930de61adc;hp=18baca1937f77f7e2ae3bc8d39b1aada845f2bd4;hb=485841aab90380ffecbe0f217eb234a64f69bb25;hpb=93dd6e5ecfa09f52a9aa17909df51d09a0a0a6ff diff --git a/README b/README index 18baca1..e1aa305 100644 --- a/README +++ b/README @@ -2,7 +2,7 @@ NAME indirect - Lexically warn about using the indirect object syntax. VERSION - Version 0.13 + Version 0.23 SYNOPSIS # In a script @@ -12,11 +12,13 @@ SYNOPSIS use indirect; my $y = new Pear; # ok { - no indirect hook => sub { die "You really wanted $_[0]\->$_[1]" }; - my $z = new Pineapple 'fresh'; # croaks 'You really wanted Pineapple->new' + 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 @@ -29,50 +31,98 @@ SYNOPSIS 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. + + 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 + , + Matt S. Trout gives an example of an indirect construct that can cause a + particularly bewildering error. - 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". + 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 [ hook => $hook | ':fatal' ]" + "unimport [ hook => $hook | ':fatal', 'FATAL', ... ]" 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's the string ':fatal', the compilation will croak on the first - indirect syntax met. + * 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 the object name as $_[0], the method name - as $_[1], the current file as $_[2] and the line number as $_[3]. + 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 when thread-safety features. + 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 - "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 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.8. + perl 5.8.1. XSLoader (standard since perl 5.006). @@ -99,8 +149,11 @@ SUPPORT ACKNOWLEDGEMENTS Bram, for motivation and advices. + Andrew Main and Florian Ragwitz, for testing on real-life code and + reporting issues. + COPYRIGHT & LICENSE - Copyright 2008-2009 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.