This is 0.05

[perl/modules/Scope-Upper.git] / lib / Scope / Upper.pm

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index 259ee7f839890adbb59f4c8184e2bd2b000470f4..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.03
+Version 0.05
 
 =cut
 
 our $VERSION;
 BEGIN {
- $VERSION = '0.03';
+ $VERSION = '0.05';
 }
 
 =head1 SYNOPSIS
@@ -56,10 +56,31 @@ BEGIN {
      ...
     } # "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
+
 =head1 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.
+You can also return to an upper level and know which context was in use then.
 
 =head1 FUNCTIONS
 
@@ -139,7 +160,30 @@ C<$key> is ignored.
 =head2 C<unwind @values, $level>
 
 Returns C<@values> I<from> the context indicated by C<$level>, i.e. from the subroutine, eval or format just above C<$level>.
+
 The upper level isn't coerced onto C<@values>, which is hence always evaluated in list context.
+This means that
+
+    my $num = sub {
+     my @a = ('a' .. 'z');
+     unwind @a => 0;
+    }->();
+
+will set C<$num> to C<'z'>.
+You can use L</want_at> to handle these cases.
+
+=head2 C<want_at $level>
+
+Like C<wantarray>, but for the subroutine/eval/format context just above C<$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 C<$num> to C<26>.
 
 =head1 WORDS
 
@@ -169,11 +213,21 @@ The level of the closest eval context above C<$from>.
 
 If C<$from> is omitted in any of those functions, the current level is used as the reference level.
 
+=head2 C<CALLER $stack>
+
+The level of the C<$stack>-th upper subroutine/eval/format context.
+It kind of corresponds to the context represented by C<caller $stack>, but while e.g. C<caller 0> refers to the caller context, C<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.
+
 =head1 EXPORT
 
-The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete> and L</unwind> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
+The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>,  L</unwind> and L</want_at> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
 
-Same goes for the words L</TOP>, L</HERE>, L</UP>, L</DOWN>, L</SUB> and L</EVAL> that are only exported on request, individually or by the tags C<':words'> and C<':all'>.
+Same goes for the words L</TOP>, L</HERE>, L</UP>, L</DOWN>, L</SUB>, L</EVAL> and L</CALLER> that are only exported on request, individually or by the tags C<':words'> and C<':all'>.
 
 =cut
 
@@ -181,8 +235,8 @@ use base qw/Exporter/;
 
 our @EXPORT      = ();
 our %EXPORT_TAGS = (
- funcs => [ qw/reap localize localize_elem localize_delete unwind/ ],
- words => [ qw/TOP HERE UP DOWN SUB EVAL/ ],
+ funcs => [ qw/reap localize localize_elem localize_delete unwind want_at/ ],
+ words => [ qw/TOP HERE UP DOWN SUB EVAL CALLER/ ],
 );
 our @EXPORT_OK   = map { @$_ } values %EXPORT_TAGS;
 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];