Also apply the context overwrite workaround when not under OP_DIE

[perl/modules/Scope-Upper.git] / README

diff --git a/README b/README
index 8dd7b5d74759860924adbc5b5fa70414af196113..074581cbe7cf8130d2d391cbbc85974e775d7b8f 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,7 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
     Scope::Upper - Act on upper scopes.
 
 VERSION

-    Version 0.06
+    Version 0.10

 
 SYNOPSIS
         package X;
 
 SYNOPSIS
         package X;


@@ -57,33 +57,39 @@ SYNOPSIS
         sub zap {
          try {
           return @things; # returns to try() and then outside zap()
         sub zap {
          try {
           return @things; # returns to try() and then outside zap()

+          # not reached

          }
          }

+         # not reached

         }
 
         my @what = zap(); # @what contains @things
 
 DESCRIPTION
         }
 
         my @what = zap(); # @what contains @things
 
 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.
+    This module lets you defer actions *at run-time* that will take place
+    when the control flow returns into an upper scope. Currently, you can:
+
+    *   hook an upper scope end with "reap" ;
+
+    *   localize variables, array/hash values or deletions of elements in
+        higher contexts with respectively "localize", "localize_elem" and
+        "localize_delete" ;
+
+    *   return values immediately to an upper level with "unwind", and know
+        which context was in use then with "want_at".

 
 FUNCTIONS
     In all those functions, $context refers to the target scope.
 
 
 FUNCTIONS
     In all those functions, $context refers to the target scope.
 

-    You have to use one or a combination of "WORDS" to build the $context to
-    pass to these functions. This is needed in order to ensure that the
-    module still works when your program is ran in the debugger. Don't try
-    to use a raw value or things will get messy.
-
-    The only thing you can assume is that it is an *absolute* indicator of
-    the frame. This means that you can safely store it at some point and use
-    it when needed, and it will still denote the original scope.
+    You have to use one or a combination of "WORDS" to build the $context
+    passed to these functions. This is needed in order to ensure that the
+    module still works when your program is ran in the debugger. The only
+    thing you can assume is that it is an *absolute* indicator of the frame,
+    which means that you can safely store it at some point and use it when
+    needed, and it will still denote the original scope.

 
   "reap $callback, $context"
 
   "reap $callback, $context"

-    Add a destructor that calls $callback when the upper scope represented
-    by $context ends.
+    Add a destructor that calls $callback (in void context) when the upper
+    scope represented by $context ends.

 
   "localize $what, $value, $context"
     A "local" delayed to the time of first return into the upper scope
 
   "localize $what, $value, $context"
     A "local" delayed to the time of first return into the upper scope


@@ -137,7 +143,9 @@ FUNCTIONS
 
   "unwind @values, $context"
     Returns @values *from* the context pointed by $context, i.e. from the
 
   "unwind @values, $context"
     Returns @values *from* the context pointed by $context, i.e. from the

-    subroutine, eval or format just above $context.
+    subroutine, eval or format just above $context, and immediately restart
+    the program flow at this point - thus effectively returning to (or from,
+    depending on how you see it) an upper context.

 
     The upper context isn't coerced onto @values, which is hence always
     evaluated in list context. This means that
 
     The upper context isn't coerced onto @values, which is hence always
     evaluated in list context. This means that


@@ -145,6 +153,7 @@ FUNCTIONS
         my $num = sub {
          my @a = ('a' .. 'z');
          unwind @a => HERE;
         my $num = sub {
          my @a = ('a' .. 'z');
          unwind @a => HERE;

+         # not reached

         }->();
 
     will set $num to 'z'. You can use "want_at" to handle these cases.
         }->();
 
     will set $num to 'z'. You can use "want_at" to handle these cases.


@@ -158,9 +167,14 @@ FUNCTIONS
         my $num = sub {
          my @a = ('a' .. 'z');
          unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
         my $num = sub {
          my @a = ('a' .. 'z');
          unwind +(want_at(HERE) ? @a : scalar @a) => HERE;

+         # not reached

         }->();
 
         }->();
 

-    will righteously set $num to 26.
+    will rightfully set $num to 26.
+
+CONSTANTS
+  "SU_THREADSAFE"
+    True iff the module could have been built when thread-safety features.

 
 WORDS
   Constants
 
 WORDS
   Constants


@@ -178,10 +192,12 @@ WORDS
     The context of the scope just above $from.
 
    "SUB $from"
     The context of the scope just above $from.
 
    "SUB $from"

-    The context of the closest subroutine above $from.
+    The context of the closest subroutine above $from. Note that $from is
+    returned if it is already a subroutine context ; hence "SUB SUB == SUB".

 
    "EVAL $from"
 
    "EVAL $from"

-    The context of the closest eval above $from.
+    The context of the closest eval above $from. Note that $from is returned
+    if it is already an eval context ; hence "EVAL EVAL == EVAL".

 
   Getting a context from a level
     Here, $level should denote a number of scopes above the current one.
 
   Getting a context from a level
     Here, $level should denote a number of scopes above the current one.


@@ -197,11 +213,72 @@ WORDS
     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
     the top scope in the current context.
 
     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
     the top scope in the current context.
 

+  Examples
+    Where "reap" fires depending on the $cxt :
+
+        sub {
+         eval {
+          sub {
+           {
+            reap \&cleanup => $cxt;
+            ...
+           }     # $cxt = SCOPE(0), or HERE
+           ...
+          }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+          ...
+         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+         ...
+        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        ...
+
+    Where "localize", "localize_elem" and "localize_delete" act depending on
+    the $cxt :
+
+        sub {
+         eval {
+          sub {
+           {
+            localize '$x' => 1 => $cxt;
+            # $cxt = SCOPE(0), or HERE
+            ...
+           }
+           # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+           ...
+          }->();
+          # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+          ...
+         };
+         # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+         ...
+        }->();
+        # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP
+        ...
+
+    Where "unwind" and "want_at" point to depending on the $cxt:
+
+        sub {
+         eval {
+          sub {
+           {
+            unwind @things => $cxt;
+            ...
+           }
+           ...
+          }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
+          ...
+         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+         ...
+        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        ...
+

 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",
     "unwind" and "want_at" are only exported on request, either individually
     or by the tags ':funcs' and ':all'.
 
 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",
     "unwind" and "want_at" are only exported on request, either individually
     or by the tags ':funcs' and ':all'.
 

+    The constant "SU_THREADSAFE" is also only exported on request,
+    individually or by the tags ':consts' and ':all'.
+

     Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
     "CALLER" that are only exported on request, individually or by the tags
     ':words' and ':all'.
     Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
     "CALLER" that are only exported on request, individually or by the tags
     ':words' and ':all'.


@@ -228,14 +305,16 @@ CAVEATS
     The first case is "solved" by moving the "local" before the "reap", and
     the second by using "localize" instead of "reap".
 
     The first case is "solved" by moving the "local" before the "reap", and
     the second by using "localize" instead of "reap".
 

-    "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
-    blocks, hence calling those functions in "import" is deemed to be
-    useless. This is an hopeless case because "BEGIN" blocks are executed
+    The effects of "reap", "localize" and "localize_elem" can't cross
+    "BEGIN" blocks, hence calling those functions in "import" is deemed to
+    be useless. This is an hopeless case because "BEGIN" blocks are executed

     once while localizing constructs should do their job at each run.
     once while localizing constructs should do their job at each run.

+    However, it's possible to hook the end of the current scope compilation
+    with B::Hooks::EndOfScope.

 
     Some rare oddities may still happen when running inside the debugger. It
     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
 
     Some rare oddities may still happen when running inside the debugger. It
     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some

-    context fixes.
+    context-related fixes.

 
 DEPENDENCIES
     XSLoader (standard since perl 5.006).
 
 DEPENDENCIES
     XSLoader (standard since perl 5.006).


@@ -243,6 +322,11 @@ DEPENDENCIES
 SEE ALSO
     Alias, Hook::Scope, Scope::Guard, Guard.
 
 SEE ALSO
     Alias, Hook::Scope, Scope::Guard, Guard.
 

+    Continuation::Escape is a thin wrapper around Scope::Upper that gives
+    you a continuation passing style interface to "unwind". It's easier to
+    use, but it requires you to have control over the scope where you want
+    to return.
+

 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 
 AUTHOR
     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 


@@ -269,7 +353,7 @@ ACKNOWLEDGEMENTS
     Thanks to Shawn M. Moore for motivation.
 
 COPYRIGHT & LICENSE
     Thanks to Shawn M. Moore for motivation.
 
 COPYRIGHT & LICENSE

-    Copyright 2008-2009 Vincent Pit, all rights reserved.
+    Copyright 2008,2009,2010 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.
 
     This program is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself.