X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2Findirect.git;a=blobdiff_plain;f=README;h=a563ea0adc3a9a95c73022856fa910878e409c71;hp=29e4f47580db0dada5efad785a2f15e77ca98493;hb=e3cc63669e7d84f338348281f313709bae0be8af;hpb=554466eac93eb0abec78e190fe175b03eec782f2

diff --git a/README b/README
index 29e4f47..a563ea0 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     indirect - Lexically warn about using the indirect object syntax.
 
 VERSION
-    Version 0.14
+    Version 0.21
 
 SYNOPSIS
         # In a script
@@ -12,10 +12,12 @@ 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'
          }
         }
+        try { ... }; # warns
+
         no indirect ':fatal';
         if (defied $foo) { ... } # croaks, note the typo
 
@@ -29,15 +31,18 @@ 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 "swoosh" isn't defined, "swoosh $x"
-    actually compiles to "$x->swoosh").
+    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" isn't 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 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.
 
@@ -50,17 +55,52 @@ METHODS
         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 reenable 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
@@ -76,8 +116,11 @@ CAVEATS
     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).
 
@@ -104,8 +147,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.