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

diff --git a/README b/README
index 5e2fb7e..8dd7b5d 100644
--- a/README
+++ b/README
@@ -2,12 +2,12 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.02
+    Version 0.06
 
 SYNOPSIS
         package X;
 
-        use Scope::Upper qw/reap localize localize_elem/;
+        use Scope::Upper qw/reap localize localize_elem localize_delete :words/;
 
         sub desc { shift->{desc} }
 
@@ -15,43 +15,79 @@ SYNOPSIS
          my ($desc) = @_;
 
          # First localize $x so that it gets destroyed last
-         localize '$x' => bless({ desc => $desc }, __PACKAGE__) => 1;
+         localize '$x' => bless({ desc => $desc }, __PACKAGE__) => UP; # one scope up
 
          reap sub {
           my $pkg = caller;
           my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
           print $x->desc . ": done\n";
-         } => 1;
+         } => SCOPE 1; # same as UP here
 
          localize_elem '%SIG', '__WARN__' => sub {
           my $pkg = caller;
           my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
           CORE::warn($x->desc . ': ' . join('', @_));
-         } => 1;
+         } => UP CALLER 0; # same as UP here
+
+         # delete last @ARGV element
+         localize_delete '@ARGV', -1 => UP SUB HERE; # same as UP here
         }
 
         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
 
+        package Z;
+
+        use Scope::Upper qw/unwind want_at :words/;
+
+        sub try (&) {
+         my @result = shift->();
+         my $cx = SUB UP SUB;
+         unwind +(want_at($cx) ? @result : scalar @result) => $cx;
+        }
+
+        ...
+
+        sub zap {
+         try {
+          return @things; # returns to try() and then outside zap()
+         }
+        }
+
+        my @what = zap(); # @what contains @things
+
 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. You can also return to an upper level and know which
+    context was in use then.
 
 FUNCTIONS
-  "reap $callback, $level"
-    Add a destructor that calls $callback when the $level-th upper scope
-    ends, where 0 corresponds to the current scope.
+    In all those functions, $context refers to the target scope.
+
+    You have to use one or a combination of "WORDS" to build the $context to
+    pass to these functions. This is needed in order to ensure that the
+    module still works when your program is ran in the debugger. Don't try
+    to use a raw value or things will get messy.
+
+    The only thing you can assume is that it is an *absolute* indicator of
+    the frame. This means that you can safely store it at some point and use
+    it when needed, and it will still denote the original scope.
 
-  "localize $what, $value, $level"
-    A "local" delayed to the time of first return into the $level-th upper
-    scope. $what can be :
+  "reap $callback, $context"
+    Add a destructor that calls $callback when the upper scope represented
+    by $context ends.
+
+  "localize $what, $value, $context"
+    A "local" delayed to the time of first return into the upper scope
+    denoted by $context. $what can be :
 
     *   A glob, in which case $value can either be a glob or a reference.
         "localize" follows then the same syntax as "local *x = $value". For
@@ -64,7 +100,7 @@ FUNCTIONS
         syntax as "local $x = $value", i.e. $value isn't dereferenced. For
         example,
 
-            localize '$x', \'foo' => 0;
+            localize '$x', \'foo' => HERE;
 
         will set $x to a reference to the string 'foo'. Other sigils ('@',
         '%', '&' and '*') require $value to be a reference of the
@@ -74,23 +110,101 @@ FUNCTIONS
         localization takes place and not when "localize" is called. This
         means that
 
-            sub tag { localize '$x', $_[0] => 1; }
+            sub tag { localize '$x', $_[0] => UP }
 
         will localize in the caller's namespace.
 
-  "localize_elem $what, $key, $value, $level"
+  "localize_elem $what, $key, $value, $context"
     Similar to "localize" but for array and hash elements. If $what is a
     glob, the slot to fill is determined from which type of reference $value
     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.
 
-  "TOPLEVEL"
-    Returns the level that currently represents the highest scope.
+  "localize_delete $what, $key, $context"
+    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.
+
+  "unwind @values, $context"
+    Returns @values *from* the context pointed by $context, i.e. from the
+    subroutine, eval or format just above $context.
+
+    The upper context isn't coerced onto @values, which is hence always
+    evaluated in list context. This means that
+
+        my $num = sub {
+         my @a = ('a' .. 'z');
+         unwind @a => HERE;
+        }->();
+
+    will set $num to 'z'. You can use "want_at" to handle these cases.
+
+  "want_at $context"
+    Like "wantarray", but for the subroutine/eval/format just above
+    $context.
+
+    The previous example can then be "corrected" :
+
+        my $num = sub {
+         my @a = ('a' .. 'z');
+         unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
+        }->();
+
+    will righteously set $num to 26.
+
+WORDS
+  Constants
+   "TOP"
+    Returns the context that currently represents the highest scope.
+
+   "HERE"
+    The context of the current scope.
+
+  Getting a context from a context
+    For any of those functions, $from is expected to be a context. When
+    omitted, it defaults to the the current context.
+
+   "UP $from"
+    The context of the scope just above $from.
+
+   "SUB $from"
+    The context of the closest subroutine above $from.
+
+   "EVAL $from"
+    The context of the closest eval above $from.
+
+  Getting a context from a level
+    Here, $level should denote a number of scopes above the current one.
+    When omitted, it defaults to 0 and those functions return the same
+    context as "HERE".
+
+   "SCOPE $level"
+    The $level-th upper context, regardless of its type.
+
+   "CALLER $level"
+    The context of the $level-th upper subroutine/eval/format. It kind of
+    corresponds to the context represented by "caller $level", but while
+    e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
+    the top scope in the current context.
 
 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",
+    "unwind" and "want_at" are only exported on request, either individually
+    or by the tags ':funcs' and ':all'.
+
+    Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
+    "CALLER" that are only exported on request, individually or by the tags
+    ':words' and ':all'.
 
 CAVEATS
     Be careful that local variables are restored in the reverse order in
@@ -98,7 +212,7 @@ CAVEATS
 
         local $x = 0;
         {
-         reap sub { print $x } => 0;
+         reap sub { print $x } => HERE;
          local $x = 1;
          ...
         }
@@ -106,7 +220,7 @@ CAVEATS
         ...
         {
          local $x = 1;
-         reap sub { $x = 2 } => 0;
+         reap sub { $x = 2 } => HERE;
          ...
         }
         # $x is 0
@@ -119,6 +233,10 @@ CAVEATS
     useless. This is an hopeless case because "BEGIN" blocks are executed
     once while localizing constructs should do their job at each run.
 
+    Some rare oddities may still happen when running inside the debugger. It
+    may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
+    context fixes.
+
 DEPENDENCIES
     XSLoader (standard since perl 5.006).
 
@@ -148,8 +266,10 @@ SUPPORT
 ACKNOWLEDGEMENTS
     Inspired by Ricardo Signes.
 
+    Thanks to Shawn M. Moore for motivation.
+
 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.