Add more level words. Rename TOPLEVEL to TOP

[perl/modules/Scope-Upper.git] / README

diff --git a/README b/README
index 52a76112f566173d0ffce5d8df265a5df69b955c..499ba67abc7184f6ca249508eb9283ba139fa0bc 100644 (file)
--- a/README
+++ b/README
@@ -2,12 +2,12 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
     Scope::Upper - Act on upper scopes.
 
 VERSION

-    Version 0.01
+    Version 0.03

 
 SYNOPSIS
         package X;
 
 
 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} }
 
 
         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;
           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');
         }
 
         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
          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
 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"
 
 FUNCTIONS
   "reap $callback, $level"


@@ -60,16 +63,19 @@ FUNCTIONS
         to 1.
 
     *   A string beginning with a sigil, representing the symbol to localize
         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;
 
 
             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; }
 
 
             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.
 
     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
   "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).
 
 DEPENDENCIES
     XSLoader (standard since perl 5.006).


@@ -112,11 +160,14 @@ SUPPORT
 
         perldoc Scope::Upper
 
 
         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
 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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.