Doc fixes

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

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index 710f86cc8d3d963f3f5c26ba1f7505e4fda75b23..5cec2f57cac796382660f276b967a55eb0f96ad1 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
@@ -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
 
@@ -171,11 +215,17 @@ If C<$from> is omitted in any of those functions, the current level is used as t
 
 =head2 C<CALLER $stack>
 
-The level corresponding to the stack referenced by 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>, L</EVAL> and L</CALLER> that are only exported on request, individually or by the tags C<':words'> and C<':all'>.
 
@@ -185,7 +235,7 @@ use base qw/Exporter/;
 
 our @EXPORT      = ();
 our %EXPORT_TAGS = (
- funcs => [ qw/reap localize localize_elem localize_delete unwind/ ],
+ 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;