X-Git-Url: http://git.vpit.fr/?p=perl%2Fmodules%2FScope-Context.git;a=blobdiff_plain;f=README;fp=README;h=991e320e51b8b97a4ee84a40f19f889398b2562e;hp=3f96b7f6e0085079365a3eb0821442f94c8bb338;hb=c41de04339d9da906cb2eab1847ce1743ae691a3;hpb=6be87d59f17965b9e4e92f71727379e19929d896

diff --git a/README b/README
index 3f96b7f..991e320 100644
--- a/README
+++ b/README
@@ -3,7 +3,7 @@ NAME
     upper scope frames.
 
 VERSION
-    Version 0.02
+    Version 0.03
 
 SYNOPSIS
         use Scope::Context;
@@ -11,32 +11,33 @@ SYNOPSIS
         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.
@@ -45,10 +46,13 @@ SYNOPSIS
           # 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.
+
 DESCRIPTION
     This class provides an object-oriented interface to Scope::Upper's
     functionalities. A Scope::Context object represents a currently active
@@ -146,7 +150,8 @@ METHODS
   "gimme"
         $cxt->gimme;
 
-    Returns the context (in the sense of "wantarray" in perlfunc) in which
+    Returns the context (in the sense of "perlfunc/wantarray" : "undef" for
+    void context, '' for scalar context, and true for list context) in which
     the scope denoted by the invocant is executed.
 
   "eval_text"
@@ -184,9 +189,9 @@ METHODS
   "want"
         my $want = $cxt->want;
 
-    Returns the Perl context (in the sense of "wantarray" : "undef" for void
-    context, '' 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 "perlfunc/wantarray") in which
+    is executed the closest subroutine, eval or format enclosing the scope
+    pointed by the invocant.
 
   "up"
         my $up_cxt = $cxt->up;
@@ -205,7 +210,7 @@ METHODS
         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.
           }
          }
@@ -216,7 +221,7 @@ METHODS
         my $sub_cxt = $cxt->sub($frames);
         my $sub_cxt = Scope::Context->sub;
 
-    Returns a new Scope::Context object pointing to the $frames-th
+    Returns a new Scope::Context object pointing to the "$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
@@ -233,7 +238,7 @@ METHODS
         }
 
         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.
         }
 
@@ -242,8 +247,8 @@ METHODS
         my $eval_cxt = $cxt->eval($frames);
         my $eval_cxt = Scope::Context->eval;
 
-    Returns a new Scope::Context object pointing to the $frames-th "eval"
-    scope above the scope pointed by the invocant.
+    Returns a new Scope::Context object pointing to the "$frames + 1"-th
+    "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 "eval" on a Scope::Context object for the current
@@ -254,7 +259,7 @@ METHODS
 
         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.
          }->()
         }
@@ -262,31 +267,34 @@ METHODS
   "reap"
         $cxt->reap($code);
 
-    Execute $code when the scope pointed by the invocant ends.
+    Executes $code when the scope pointed by the invocant ends.
 
     See "reap" in Scope::Upper for details.
 
   "localize"
         $cxt->localize($what, $value);
 
-    Localize the variable described by $what to the value $value when the
-    control flow returns to the scope pointed by the invocant.
+    Localizes the variable described by $what to the value $value when the
+    control flow returns to the scope pointed by the invocant, until said
+    scope ends.
 
     See "localize" in Scope::Upper for details.
 
   "localize_elem"
         $cxt->localize_elem($what, $key, $value);
 
-    Localize the element $key of the variable $what to the value $value when
-    the control flow returns to the scope pointed by the invocant.
+    Localizes the element $key of the variable $what to the value $value
+    when the control flow returns to the scope pointed by the invocant,
+    until said scope ends.
 
     See "localize_elem" in Scope::Upper for details.
 
   "localize_delete"
         $cxt->localize_delete($what, $key);
 
-    Delete the element $key from the variable $what when the control flow
-    returns to the scope pointed by the invocant.
+    Deletes the element $key from the variable $what when the control flow
+    returns to the scope pointed by the invocant, and restores it to its
+    original value when said scope ends.
 
     See "localize_delete" in Scope::Upper for details.
 
@@ -318,7 +326,8 @@ METHODS
     See "uplevel" in Scope::Upper for details.
 
 DEPENDENCIES
-    Carp (core module since perl 5), Scalar::Util (since 5.7.3).
+    Carp (core module since perl 5), overload (since 5.2.0), Scalar::Util
+    (since 5.7.3).
 
     Scope::Upper 0.21.
 
@@ -345,7 +354,7 @@ SUPPORT
         perldoc Scope::Context
 
 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.