This is 0.07

diff --git a/Changes b/Changes
index c9aded4d521a2ac0bdf70c5c513919eff854a4f1..f03372c2b90f87aa11431ae66f5d360f780a71d3 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,16 @@
 Revision history for Scope-Upper
 
 Revision history for Scope-Upper
 

+0.07    2009-02-20 00:20 UTC
+        + Chg : The CLONE method will no longer be defined for non-threaded
+                perls.
+        + Doc : Some examples on how to build the target context from the words.
+        + Fix : Some unlikely possible uninitialized reads, indirectly pointed
+                out in a Redhat review request.
+        + Fix : "localize *x, 'y' => $cxt" now matches Perl's behaviour for
+                "local *x = 'y'".
+        + Fix : Miscellanous code cleanups, courtesy of Florian Ragwitz.
+        + Upd : Resources in META.yml.
+

 0.06    2009-01-17 00:05 UTC
         + Chg : INCOMPATIBLE CHANGE: The level is now absolute and no longer
                 relative to the current frame - we'll call it "context" from now
 0.06    2009-01-17 00:05 UTC
         + Chg : INCOMPATIBLE CHANGE: The level is now absolute and no longer
                 relative to the current frame - we'll call it "context" from now

diff --git a/META.yml b/META.yml
index 71bb2604c3f1a8342be17354d783520bc2a27717..99a34cb7aae7ba048b4809da04cb472c41d0e820 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -1,6 +1,6 @@
 --- #YAML:1.0
 name:               Scope-Upper
 --- #YAML:1.0
 name:               Scope-Upper

-version:            0.06
+version:            0.07

 abstract:           Act on upper scopes.
 author:
     - Vincent Pit <perl@profvince.com>
 abstract:           Act on upper scopes.
 author:
     - Vincent Pit <perl@profvince.com>


@@ -8,9 +8,18 @@ license:            perl
 distribution_type:  module
 configure_requires:
     ExtUtils::MakeMaker:  0
 distribution_type:  module
 configure_requires:
     ExtUtils::MakeMaker:  0

+build_requires:
+    ExtUtils::MakeMaker:  0
+    Test::More:           0

 requires:
     Exporter:  0
 requires:
     Exporter:  0

+    perl:      5.006

     XSLoader:  0
     XSLoader:  0

+resources:
+    bugtracker:  http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper
+    homepage:    http://search.cpan.org/dist/Scope-Upper/
+    license:     http://dev.perl.org/licenses/
+    repository:  http://git.profvince.com/perl/modules/Scope-Upper.git

 no_index:
     directory:
         - t
 no_index:
     directory:
         - t


@@ -19,6 +28,3 @@ generated_by:       ExtUtils::MakeMaker version 6.48
 meta-spec:
     url:      http://module-build.sourceforge.net/META-spec-v1.4.html
     version:  1.4
 meta-spec:
     url:      http://module-build.sourceforge.net/META-spec-v1.4.html
     version:  1.4

-build_requires:
-    ExtUtils::MakeMaker:           0
-    Test::More:                    0

diff --git a/README b/README
index 8dd7b5d74759860924adbc5b5fa70414af196113..16f88ca56cd9895c60ad6903efac19530457fa7e 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.07

 
 SYNOPSIS
         package X;
 
 SYNOPSIS
         package X;


@@ -63,23 +63,27 @@ SYNOPSIS
         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"
     Add a destructor that calls $callback when the upper scope represented
 
   "reap $callback, $context"
     Add a destructor that calls $callback when the upper scope represented


@@ -137,7 +141,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


@@ -178,10 +184,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,6 +205,64 @@ 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
 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",
     "unwind" and "want_at" are only exported on request, either individually


@@ -228,14 +294,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).

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index 5f222664e25cc614a921021c773c0fea8033de3d..3b801161f5ce315a24e70bc2041a7de7154f2134 100644 (file)
--- a/lib/Scope/Upper.pm
+++ b/lib/Scope/Upper.pm
@@ -9,13 +9,13 @@ Scope::Upper - Act on upper scopes.
 
 =head1 VERSION
 
 
 =head1 VERSION
 

-Version 0.06
+Version 0.07

 
 =cut
 
 our $VERSION;
 BEGIN {
 
 =cut
 
 our $VERSION;
 BEGIN {

- $VERSION = '0.06';
+ $VERSION = '0.07';

 }
 
 =head1 SYNOPSIS
 }
 
 =head1 SYNOPSIS