Clarify the descriptions of ->localize{,_elem,_delete}()

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

diff --git a/lib/Scope/Context.pm b/lib/Scope/Context.pm
index aa422e1b950a8ecc682e3ff1b4863588aae82e7e..c9b778e309cb301c4655aaf0035a1a2511b97c17 100644 (file)
--- a/lib/Scope/Context.pm
+++ b/lib/Scope/Context.pm
@@ -16,11 +16,11 @@ Scope::Context - Object-oriented interface for inspecting or acting upon upper s
 
 =head1 VERSION
 
-Version 0.01
+Version 0.02
 
 =cut
 
-our $VERSION = '0.01';
+our $VERSION = '0.02';
 
 =head1 SYNOPSIS
 
@@ -29,32 +29,33 @@ our $VERSION = '0.01';
     for (1 .. 5) {
      sub {
       eval {
-       # Create Scope::Context objects for different upper frames.
-       my ($block, $sub, $eval, $loop);
+       # Create Scope::Context objects for different upper frames :
+       my ($block, $eval, $sub, $loop);
        {
         $block = Scope::Context->new;
-        $sub   = $block->sub;    # = $block->up
-        $eval  = $block->eval;   # = $block->up(2)
-        $loop  = $eval->up;      # = $block->up(3)
+        $eval  = $block->eval;   # == $block->up
+        $sub   = $block->sub;    # == $block->up(2)
+        $loop  = $sub->up;       # == $block->up(3)
        }
 
        eval {
-        # This will throw an exception, since $block has expired.
+        # This throws an exception, since $block has expired :
         $block->localize('$x' => 1);
        };
 
-       # This prints "hello" when the eval block above ends.
+       # This will print "hello" when the current eval block ends :
        $eval->reap(sub { print "hello\n" });
 
-       # Ignore $SIG{__DIE__} just for the loop body.
-       $loop->localize_delete('%SIG', '__DIE__');
+       # Ignore warnings just for the loop body :
+       $loop->localize_elem('%SIG', __WARN__ => sub { });
 
-       # Execute the callback as if it ran in place of the sub.
+       # Execute the callback as if it ran in place of the sub :
        my @values = $sub->uplevel(sub {
         return @_, 2;
        }, 1);
+       # @values now contains (1, 2).
 
-       # Immediately return (1, 2, 3) from the sub, bypassing the eval.
+       # Immediately return (1, 2, 3) from the sub, bypassing the eval :
        $sub->unwind(@values, 3);
 
        # Not reached.
@@ -63,10 +64,13 @@ our $VERSION = '0.01';
       # Not reached.
      }->();
 
-     # unwind() returns here. "hello\n" was printed, and now
-     # $SIG{__DIE__} is undefined.
+     # unwind() returns here. "hello\n" was printed, and now warnings are
+     # ignored.
     }
 
+    # $SIG{__WARN__} has been restored to its original value, warnings are no
+    # longer ignored.
+
 =head1 DESCRIPTION
 
 This class provides an object-oriented interface to L<Scope::Upper>'s functionalities.
@@ -228,7 +232,7 @@ Returns a boolean indicating whether a new instance of C<@_> was set up for this
 
     $cxt->gimme;
 
-Returns the context (in the sense of L<perlfunc/wantarray>) in which the scope denoted by the invocant is executed.
+Returns the context (in the sense of C<perlfunc/wantarray> : C<undef> for void context, C<''> for scalar context, and true for list context) in which the scope denoted by the invocant is executed.
 
 =head2 C<eval_text>
 
@@ -289,7 +293,7 @@ BEGIN {
 
     my \$info = \$self->{info};
     \$info = \$self->{info} = [ Scope::Upper::context_info(\$self->cxt) ]
-                                                                        unless \$info;
+                                                                  unless \$info;
 
     return \$info->[$idx];
    }
@@ -302,7 +306,7 @@ BEGIN {
 
     my $want = $cxt->want;
 
-Returns the Perl context (in the sense of C<wantarray> : C<undef> for void context, C<''> for scalar context, and true for list context) in which is executed the scope pointed by the invocant.
+Returns the Perl context (in the sense of C<perlfunc/wantarray>) in which is executed the closest subroutine, eval or format enclosing the scope pointed by the invocant.
 
 =cut
 
@@ -329,7 +333,7 @@ If omitted, C<$frames> defaults to C<1>.
     sub {
      {
       {
-       my $up = Scope::Context->new->up(2); # = Scope::Context->up(2)
+       my $up = Scope::Context->new->up(2); # == Scope::Context->up(2)
        # $up points two contextes above this one, which is the sub.
       }
      }
@@ -361,7 +365,7 @@ sub up {
     my $sub_cxt = $cxt->sub($frames);
     my $sub_cxt = Scope::Context->sub;
 
-Returns a new L<Scope::Context> object pointing to the C<$frames>-th subroutine scope above the scope pointed by the invocant.
+Returns a new L<Scope::Context> object pointing to the C<$frames + 1>-th subroutine scope above the scope pointed by the invocant.
 
 This method can also be invoked as a class method, in which case it is equivalent to calling L</sub> on a L<Scope::Context> object for the current context.
 
@@ -374,7 +378,7 @@ If omitted, C<$frames> defaults to C<0>, which results in the closest sub enclos
     }
 
     sub inner {
-     my $sub = Scope::Context->new->sub(1); # = Scope::Context->sub(1)
+     my $sub = Scope::Context->new->sub(1); # == Scope::Context->sub(1)
      # $sub points to the context for the outer() sub.
     }
 
@@ -405,7 +409,7 @@ sub sub {
     my $eval_cxt = $cxt->eval($frames);
     my $eval_cxt = Scope::Context->eval;
 
-Returns a new L<Scope::Context> object pointing to the C<$frames>-th C<eval> scope above the scope pointed by the invocant.
+Returns a new L<Scope::Context> object pointing to the C<$frames + 1>-th C<eval> scope above the scope pointed by the invocant.
 
 This method can also be invoked as a class method, in which case it is equivalent to calling L</eval> on a L<Scope::Context> object for the current context.
 
@@ -413,7 +417,7 @@ If omitted, C<$frames> defaults to C<0>, which results in the closest eval enclo
 
     eval {
      sub {
-      my $eval = Scope::Context->new->eval; # = Scope::Context->eval
+      my $eval = Scope::Context->new->eval; # == Scope::Context->eval
       # $eval points to the eval context.
      }->()
     }
@@ -461,7 +465,7 @@ sub reap {
 
     $cxt->localize($what, $value);
 
-Localize the variable described by C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant.
+Localize the variable described by C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant, until said scope ends.
 
 See L<Scope::Upper/localize> for details.
 
@@ -479,7 +483,7 @@ sub localize {
 
     $cxt->localize_elem($what, $key, $value);
 
-Localize the element C<$key> of the variable C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant.
+Localize the element C<$key> of the variable C<$what> to the value C<$value> when the control flow returns to the scope pointed by the invocant, until said scope ends.
 
 See L<Scope::Upper/localize_elem> for details.
 
@@ -497,7 +501,7 @@ sub localize_elem {
 
     $cxt->localize_delete($what, $key);
 
-Delete the element C<$key> from the variable C<$what> when the control flow returns to the scope pointed by the invocant.
+Delete the element C<$key> from the variable C<$what> when the control flow returns to the scope pointed by the invocant, and restore it to its original value when said scope ends.
 
 See L<Scope::Upper/localize_delete> for details.
 
@@ -597,7 +601,7 @@ You can find documentation for this module with the perldoc command.
 
 =head1 COPYRIGHT & LICENSE
 
-Copyright 2011,2012,2013 Vincent Pit, all rights reserved.
+Copyright 2011,2012,2013,2015 Vincent Pit, all rights reserved.
 
 This program is free software; you can redistribute it and/or modify it
 under the same terms as Perl itself.