This is 0.05

diff --git a/Changes b/Changes
index 008517eb3e1ca31e074d609aa043bc67ae085e39..93d66200de9a09627f2d9879e73bf9fb0361944f 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,12 @@
 Revision history for Scope-Upper
 
+0.05    2009-01-12 18:15 UTC
+        + Fix : Stack mess when using unwind() in scalar context.
+        + Fix : Returning an automatic variable isn't wise, so let's use a
+                context instead.
+        + Doc : Clarifications.
+        + Tst : Stress tests for unwind().
+
 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.

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

diff --git a/README b/README
index c6d5711fc1c48803145c44c8e5cc143497a5efa0..feecd5c772b15f2e41961756e0e81892159d3834 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
-    Version 0.04
+    Version 0.05
 
 SYNOPSIS
         package X;
@@ -65,7 +65,8 @@ 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.
+    in higher contexts. You can also return to an upper level and know which
+    context was in use then.
 
 FUNCTIONS
   "reap $callback, $level"
@@ -124,13 +125,31 @@ FUNCTIONS
 
   "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.
+    subroutine, eval or format just above $level.
+
+    The upper level 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 => 0;
+        }->();
+
+    will set $num to 'z'. You can use "want_at" to handle these cases.
 
   "want_at $level"
     Like "wantarray", but for the subroutine/eval/format context just above
     $level.
 
+    The previous example can then be "corrected" :
+
+        my $num = sub {
+         my @a = ('a' .. 'z');
+         unwind +(want_at(0) ? @a : scalar @a) => 0;
+        }->();
+
+    will righteously set $num to 26.
+
 WORDS
   "TOP"
     Returns the level that currently represents the highest scope.
@@ -154,7 +173,14 @@ WORDS
     as the reference level.
 
   "CALLER $stack"
-    The level corresponding to the stack referenced by "caller $stack".
+    The level of the $stack-th upper subroutine/eval/format context. It kind
+    of corresponds to the context represented by "caller $stack", but while
+    e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
+    the top scope in the current context. For example,
+
+        reap ... => CALLER(0)
+
+    will fire the destructor when the current subroutine/eval/format ends.
 
 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index 5cec2f57cac796382660f276b967a55eb0f96ad1..4fb21d543a3f1adcfb791adf73fe7c79c144f9c5 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.04
+Version 0.05
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.04';
+ $VERSION = '0.05';
 }
 
 =head1 SYNOPSIS