X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=5e2fb7e35e9345a478ab473f5744fd83ab65b279;hb=5d565c2feed583ba26f5451a0b25f1a5df2be4ed;hp=52a76112f566173d0ffce5d8df265a5df69b955c;hpb=ac794d1f5c02a97322dad2aa7e435466395cb928;p=perl%2Fmodules%2FScope-Upper.git

diff --git a/README b/README
index 52a7611..5e2fb7e 100644
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.01
+    Version 0.02
 
 SYNOPSIS
         package X;
@@ -60,16 +60,19 @@ FUNCTIONS
         to 1.
 
     *   A string beginning with a sigil, representing the symbol to localize
-        and assign to. If the sigil is '$', then $value isn't dereferenced,
-        that is
+        and to assign to. If the sigil is '$', "localize" follows the same
+        syntax as "local $x = $value", i.e. $value isn't dereferenced. For
+        example,
 
             localize '$x', \'foo' => 0;
 
-        will set $x to a reference to the string 'foo'. Other sigils behave
-        as if a glob was passed.
+        will set $x to a reference to the string 'foo'. Other sigils ('@',
+        '%', '&' and '*') require $value to be a reference of the
+        corresponding type.
 
-        The symbol is resolved when the actual localization takes place and
-        not when "localize" is called. This means that
+        When the symbol is given by a string, it is resolved when the actual
+        localization takes place and not when "localize" is called. This
+        means that
 
             sub tag { localize '$x', $_[0] => 1; }
 
@@ -89,6 +92,33 @@ EXPORT
     only exported on request, either individually or by the tags ':funcs'
     and ':all'.
 
+CAVEATS
+    Be careful that local variables are restored in the reverse order in
+    which they were localized. Consider those examples:
+
+        local $x = 0;
+        {
+         reap sub { print $x } => 0;
+         local $x = 1;
+         ...
+        }
+        # prints '0'
+        ...
+        {
+         local $x = 1;
+         reap sub { $x = 2 } => 0;
+         ...
+        }
+        # $x is 0
+
+    The first case is "solved" by moving the "local" before the "reap", and
+    the second by using "localize" instead of "reap".
+
+    "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
+    blocks, hence calling those functions in "import" is deemed to be
+    useless. This is an hopeless case because "BEGIN" blocks are executed
+    once while localizing constructs should do their job at each run.
+
 DEPENDENCIES
     XSLoader (standard since perl 5.006).
 
@@ -112,6 +142,9 @@ SUPPORT
 
         perldoc Scope::Upper
 
+    Tests code coverage report is available at
+    <http://www.profvince.com/perl/cover/Scope-Upper>.
+
 ACKNOWLEDGEMENTS
     Inspired by Ricardo Signes.