X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=499ba67abc7184f6ca249508eb9283ba139fa0bc;hb=02798a015a7fae0ff3d924b3270def3996e4210b;hp=52a76112f566173d0ffce5d8df265a5df69b955c;hpb=bac4fc46c2d48ce5db75de6c88e0983aeeedf865;p=perl%2Fmodules%2FScope-Upper.git

diff --git a/README b/README
index 52a7611..499ba67 100644
--- a/README
+++ b/README
@@ -2,12 +2,12 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.01
+    Version 0.03
 
 SYNOPSIS
         package X;
 
-        use Scope::Upper qw/reap localize localize_elem/;
+        use Scope::Upper qw/reap localize localize_elem localize_delete/;
 
         sub desc { shift->{desc} }
 
@@ -28,13 +28,15 @@ SYNOPSIS
           my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
           CORE::warn($x->desc . ': ' . join('', @_));
          } => 1;
+
+         localize_delete '@ARGV', $#ARGV => 1; # delete last @ARGV element
         }
 
         package Y;
 
         {
          X::set_tag('pie');
-         # $x is now a X object
+         # $x is now a X object, and @ARGV has one element less
          warn 'what'; # warns "pie: what at ..."
          ...
         } # "pie: done" is printed
@@ -42,7 +44,8 @@ SYNOPSIS
 DESCRIPTION
     This module lets you defer actions that will take place when the control
     flow returns into an upper scope. Currently, you can hook an upper scope
-    end, or localize variables and array/hash values in higher contexts.
+    end, or localize variables, array/hash values or deletions of elements
+    in higher contexts.
 
 FUNCTIONS
   "reap $callback, $level"
@@ -60,16 +63,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; }
 
@@ -81,13 +87,55 @@ FUNCTIONS
     is ; otherwise it's inferred from the sigil. $key is either an array
     index or a hash key, depending of which kind of variable you localize.
 
+  "localize_delete $what, $key, $level"
+    Similiar to "localize", but for deleting variables or array/hash
+    elements. $what can be:
+
+    *   A glob, in which case $key is ignored and the call is equivalent to
+        "local *x".
+
+    *   A string beginning with '@' or '%', for which the call is equivalent
+        to respectiveley "local $a[$key]; delete $a[$key]" and "local
+        $h{$key}; delete $h{$key}".
+
+    *   A string beginning with '&', which more or less does "undef &func"
+        in the upper scope. It's actually more powerful, as &func won't even
+        "exists" anymore. $key is ignored.
+
   "TOPLEVEL"
     Returns the level that currently represents the highest scope.
 
 EXPORT
-    The functions "reap", "localize", "localize_elem" and "TOPLEVEL" are
-    only exported on request, either individually or by the tags ':funcs'
-    and ':all'.
+    The functions "reap", "localize", "localize_elem", "localize_delete" and
+    "TOPLEVEL" are 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,11 +160,14 @@ SUPPORT
 
         perldoc Scope::Upper
 
+    Tests code coverage report is available at
+    <http://www.profvince.com/perl/cover/Scope-Upper>.
+
 ACKNOWLEDGEMENTS
     Inspired by Ricardo Signes.
 
 COPYRIGHT & LICENSE
-    Copyright 2008 Vincent Pit, all rights reserved.
+    Copyright 2008-2009 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.