This is 0.04

diff --git a/Changes b/Changes
index cfa7084c9d09631e816bb6192c05673f4a1e6c4d..008517eb3e1ca31e074d609aa043bc67ae085e39 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,14 @@
 Revision history for Scope-Upper
 
+0.04    2009-01-11 18:40 UTC
+        + Add : unwind(@things, $level), that returns to an upper context.
+        + Add : want_at($level), that gives the wantarray for $level.
+        + Add : Control words, to reliably get the level of the n-th upper
+                subroutine or eval scope. TOPLEVEL was renamed to TOP.
+        + Fix : Tests with 5.6.
+        + Tst : Reordering and factoring some of the stress tests so that they
+                aren't needlessly ran several times.
+
 0.03    2009-01-04 15:55 UTC
         + Add : localize_delete(), that localize array/hash elements in upper
                 scopes.

diff --git a/META.yml b/META.yml
index 79953f5aba99d69af5d5eeb8e23cb53e810d4aa8..636f298042ffc50f3093f90c229b7e85310dbfc0 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,6 +1,6 @@
 --- #YAML:1.0
 name:               Scope-Upper
-version:            0.03
+version:            0.04
 abstract:           Act on upper scopes.
 author:
     - Vincent Pit <perl@profvince.com>

diff --git a/README b/README
index 499ba67abc7184f6ca249508eb9283ba139fa0bc..c6d5711fc1c48803145c44c8e5cc143497a5efa0 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.03
+    Version 0.04
 
 SYNOPSIS
         package X;
@@ -41,6 +41,26 @@ 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()
+         }
+        }
+
+        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
@@ -102,13 +122,48 @@ FUNCTIONS
         in the upper scope. It's actually more powerful, as &func won't even
         "exists" anymore. $key is ignored.
 
-  "TOPLEVEL"
+  "unwind @values, $level"
+    Returns @values *from* the context indicated by $level, i.e. from the
+    subroutine, eval or format just above $level. The upper level isn't
+    coerced onto @values, which is hence always evaluated in list context.
+
+  "want_at $level"
+    Like "wantarray", but for the subroutine/eval/format context just above
+    $level.
+
+WORDS
+  "TOP"
     Returns the level that currently represents the highest scope.
 
+  "HERE"
+    The current level - i.e. 0.
+
+  "UP $from"
+    The level of the scope just above $from.
+
+  "DOWN $from"
+    The level of the scope just below $from.
+
+  "SUB $from"
+    The level of the closest subroutine context above $from.
+
+  "EVAL $from"
+    The level of the closest eval context above $from.
+
+    If $from is omitted in any of those functions, the current level is used
+    as the reference level.
+
+  "CALLER $stack"
+    The level corresponding to the stack referenced by "caller $stack".
+
 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", "DOWN", "SUB", "EVAL" 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

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index ba26e61291537cb5049c51732a7ecc25036f8247..66f225f8a3f60913f54734a1dd94b608bbeb6945 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.03
+Version 0.04
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.03';
+ $VERSION = '0.04';
 }
 
 =head1 SYNOPSIS