X-Git-Url: http://git.vpit.fr/?a=blobdiff_plain;f=README;h=d0327e14cd8e52e39197258c9761d383e6849ed2;hb=4c8461e81387b2f965156423ae04f418d8da1312;hp=499ba67abc7184f6ca249508eb9283ba139fa0bc;hpb=c8549c2d49ee305498c19318c51dc6540dba8b3f;p=perl%2Fmodules%2FScope-Upper.git

diff --git a/README b/README
index 499ba67..d0327e1 100644
--- a/README
+++ b/README
@@ -2,12 +2,12 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.03
+    Version 0.08
 
 SYNOPSIS
         package X;
 
-        use Scope::Upper qw/reap localize localize_elem localize_delete/;
+        use Scope::Upper qw/reap localize localize_elem localize_delete :words/;
 
         sub desc { shift->{desc} }
 
@@ -15,21 +15,22 @@ 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
 
-         localize_delete '@ARGV', $#ARGV => 1; # delete last @ARGV element
+         # delete last @ARGV element
+         localize_delete '@ARGV', -1 => UP SUB HERE; # same as UP here
         }
 
         package Y;
@@ -41,20 +42,58 @@ SYNOPSIS
          ...
         } # "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()
+          # not reached
+         }
+         # not reached
+        }
+
+        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, array/hash values or deletions of elements
-    in higher contexts.
+    This module lets you defer actions *at run-time* that will take place
+    when the control flow returns into an upper scope. Currently, you can:
+
+    *   hook an upper scope end with "reap" ;
+
+    *   localize variables, array/hash values or deletions of elements in
+        higher contexts with respectively "localize", "localize_elem" and
+        "localize_delete" ;
+
+    *   return values immediately to an upper level with "unwind", and know
+        which context was in use then with "want_at".
 
 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
+    passed to these functions. This is needed in order to ensure that the
+    module still works when your program is ran in the debugger. The only
+    thing you can assume is that it is an *absolute* indicator of the frame,
+    which 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 (in void context) 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
@@ -67,7 +106,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
@@ -77,17 +116,17 @@ 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.
 
-  "localize_delete $what, $key, $level"
+  "localize_delete $what, $key, $context"
     Similiar to "localize", but for deleting variables or array/hash
     elements. $what can be:
 
@@ -102,13 +141,140 @@ FUNCTIONS
         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.
+  "unwind @values, $context"
+    Returns @values *from* the context pointed by $context, i.e. from the
+    subroutine, eval or format just above $context, and immediately restart
+    the program flow at this point - thus effectively returning to (or from,
+    depending on how you see it) an upper 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;
+         # not reached
+        }->();
+
+    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;
+         # not reached
+        }->();
+
+    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. Note that $from is
+    returned if it is already a subroutine context ; hence "SUB SUB == SUB".
+
+   "EVAL $from"
+    The context of the closest eval above $from. Note that $from is returned
+    if it is already an eval context ; hence "EVAL EVAL == EVAL".
+
+  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.
+
+  Examples
+    Where "reap" fires depending on the $cxt :
+
+        sub {
+         eval {
+          sub {
+           {
+            reap \&cleanup => $cxt;
+            ...
+           }     # $cxt = SCOPE(0), or HERE
+           ...
+          }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+          ...
+         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+         ...
+        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        ...
+
+    Where "localize", "localize_elem" and "localize_delete" act depending on
+    the $cxt :
+
+        sub {
+         eval {
+          sub {
+           {
+            localize '$x' => 1 => $cxt;
+            # $cxt = SCOPE(0), or HERE
+            ...
+           }
+           # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+           ...
+          }->();
+          # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+          ...
+         };
+         # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+         ...
+        }->();
+        # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP
+        ...
+
+    Where "unwind" and "want_at" point to depending on the $cxt:
+
+        sub {
+         eval {
+          sub {
+           {
+            unwind @things => $cxt;
+            ...
+           }
+           ...
+          }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
+          ...
+         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+         ...
+        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        ...
 
 EXPORT
-    The functions "reap", "localize", "localize_elem", "localize_delete" 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
@@ -116,7 +282,7 @@ CAVEATS
 
         local $x = 0;
         {
-         reap sub { print $x } => 0;
+         reap sub { print $x } => HERE;
          local $x = 1;
          ...
         }
@@ -124,7 +290,7 @@ CAVEATS
         ...
         {
          local $x = 1;
-         reap sub { $x = 2 } => 0;
+         reap sub { $x = 2 } => HERE;
          ...
         }
         # $x is 0
@@ -132,10 +298,16 @@ CAVEATS
     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
+    The effects of "reap", "localize" and "localize_elem" 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.
+    However, it's possible to hook the end of the current scope compilation
+    with B::Hooks::EndOfScope.
+
+    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-related fixes.
 
 DEPENDENCIES
     XSLoader (standard since perl 5.006).
@@ -166,6 +338,8 @@ SUPPORT
 ACKNOWLEDGEMENTS
     Inspired by Ricardo Signes.
 
+    Thanks to Shawn M. Moore for motivation.
+
 COPYRIGHT & LICENSE
     Copyright 2008-2009 Vincent Pit, all rights reserved.