This is 0.02

diff --git a/Changes b/Changes
index 7cb3a02ed6621fb399b3e0143db6b9664a64f934..e872d83930b2eb8f6838f088a147a6e65aa18125 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,11 @@
 Revision history for Scope-Upper
 
+0.02    2008-12-28 18:40 UTC
+        + Doc : Clarifications and improvements.
+        + Fix : Missing compatibility macros.
+        + Fix : Localized nonexistant array elements should be deleted when
+                their time comes so that the array recovers its original length.
+
 0.01    2008-12-26 16:05 UTC
         First version, released on an unsuspecting world.
 

diff --git a/META.yml b/META.yml
index c56dad6f74ce5c8b0710950f57bcc7037ed20441..12989c56a8f8b84bfa3ac701f615afdefbfee54f 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,6 +1,6 @@
 --- #YAML:1.0
 name:               Scope-Upper
-version:            0.01
+version:            0.02
 abstract:           Act on upper scopes.
 author:
     - Vincent Pit <perl@profvince.com>
@@ -9,6 +9,7 @@ distribution_type:  module
 configure_requires:
     ExtUtils::MakeMaker:  0
 requires:
+    Exporter:  0
     XSLoader:  0
 no_index:
     directory:

diff --git a/README b/README
index 52a76112f566173d0ffce5d8df265a5df69b955c..5e2fb7e35e9345a478ab473f5744fd83ab65b279 100644 (file)
--- 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.
 

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index ae9683d3aba0e4ed0069e211620f1df3d9e19dc0..f4e276daa3d00a4890aa37681cf30052b3cdefc8 100644 (file)
--- a/lib/Scope/Upper.pm
+++ b/lib/Scope/Upper.pm
@@ -9,13 +9,13 @@ Scope::Upper - Act on upper scopes.
 
 =head1 VERSION
 
-Version 0.01
+Version 0.02
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.01';
+ $VERSION = '0.02';
 }
 
 =head1 SYNOPSIS