This is 0.20

diff --git a/Changes b/Changes
index 6a9695192f17387641c51c6098775aa63689bbb2..1b941330f7e1673bdf5945f32ae16b657800eeda 100644 (file)
--- a/Changes
+++ b/Changes
@@ -1,5 +1,23 @@
 Revision history for Scope-Upper
 
 Revision history for Scope-Upper
 

+0.20    2012-09-17 11:00 UTC
+        + Add : The new yield(@values, $context) function can be used to return
+                values to any upper scope, including do or map blocks.
+                The new leave(@values) function is an alias for
+                yield(@values, HERE).
+        + Add : The new context_info($context) function return information
+                about context $context, similarly to what caller() provides
+                but for any upper scope.
+        + Chg : Contexts are now normalized. In previous versions, it was
+                possible for different contexts to refer to the same scope :
+                for example, "for (my $i = 0; $i < 10; ++$i) { ... }" was
+                reachable through two contexts, while "for (@array) { ... }"
+                only by one. Starting from this version, contexts are
+                normalized so that they always represent an actual scope.
+        + Doc : C++ compilers are officially NOT supported.
+        + Fix : Building with a more recent version of perl 5.17.4.
+        + Fix : Debugger compatibility with perl 5.17.1 and above.
+

 0.19    2012-09-01 13:25 UTC
         + Doc : POD headings have been made linkable.
         + Fix : Building with perl 5.17.4.
 0.19    2012-09-01 13:25 UTC
         + Doc : POD headings have been made linkable.
         + Fix : Building with perl 5.17.4.

diff --git a/META.json b/META.json
index 544e4ce0c9014d728ecc367ba60ce35e1e0d1da3..65c01ceaac630e66beef2c2b8a2f8d035f13acd4 100644 (file)
--- a/META.json
+++ b/META.json
@@ -57,5 +57,5 @@
          "url" : "http://git.profvince.com/?p=perl%2Fmodules%2FScope-Upper.git"
       }
    },
          "url" : "http://git.profvince.com/?p=perl%2Fmodules%2FScope-Upper.git"
       }
    },

-   "version" : "0.19"
+   "version" : "0.20"

 }
 }

diff --git a/META.yml b/META.yml
index 572d3741814f0a4bf277246900919b1b421c1de7..468b3c3eab9df3b89fcf5820c46d8df6566a504f 100644 (file)
--- a/META.yml
+++ b/META.yml
@@ -32,4 +32,4 @@ resources:
   homepage: http://search.cpan.org/dist/Scope-Upper/
   license: http://dev.perl.org/licenses/
   repository: http://git.profvince.com/?p=perl%2Fmodules%2FScope-Upper.git
   homepage: http://search.cpan.org/dist/Scope-Upper/
   license: http://dev.perl.org/licenses/
   repository: http://git.profvince.com/?p=perl%2Fmodules%2FScope-Upper.git

-version: 0.19
+version: 0.20

diff --git a/README b/README
index e09bd1230a0ccc5c13b1fd17e90188bb56a9a6c5..46c4cc0a43538bfefc7fea447853a189ba3abd98 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.19
+    Version 0.20

 
 SYNOPSIS
     "reap", "localize", "localize_elem", "localize_delete" and "WORDS" :
 
 SYNOPSIS
     "reap", "localize", "localize_elem", "localize_delete" and "WORDS" :


@@ -148,8 +148,11 @@ DESCRIPTION
         higher contexts with respectively "localize", "localize_elem" and
         "localize_delete" ;
 
         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" ;
+    *   return values immediately to an upper level with "unwind", "yield"
+        and "leave" ;
+
+    *   gather information about an upper context with "want_at" and
+        "context_info" ;

 
     *   execute a subroutine in the setting of an upper subroutine stack
         frame with "uplevel" ;
 
     *   execute a subroutine in the setting of an upper subroutine stack
         frame with "uplevel" ;


@@ -246,7 +249,10 @@ FUNCTIONS
     will be vivified as soon as the localization occurs and emptied when it
     ends, although it will still exist in its glob.
 
     will be vivified as soon as the localization occurs and emptied when it
     ends, although it will still exist in its glob.
 

-  "localize_delete $what, $key, $context"
+  "localize_delete"
+        localize_delete $what, $key;
+        localize_delete $what, $key, $context;
+

     Introduces the deletion of a variable or an array/hash element delayed
     to the time of first return into the upper scope denoted by $context.
     $what can be:
     Introduces the deletion of a variable or an array/hash element delayed
     to the time of first return into the upper scope denoted by $context.
     $what can be:


@@ -263,13 +269,15 @@ FUNCTIONS
         "exists" anymore. $key is ignored.
 
   "unwind"
         "exists" anymore. $key is ignored.
 
   "unwind"

-        unwind @values;
+        unwind;

         unwind @values, $context;
 
         unwind @values, $context;
 

-    Returns @values *from* the context pointed by $context, i.e. from the
-    subroutine, eval or format at or just above $context, and immediately
-    restart the program flow at this point - thus effectively returning to
-    an upper scope.
+    Returns @values *from* the subroutine, eval or format context pointed by
+    or just above $context, and immediately restart the program flow at this
+    point - thus effectively returning @values to an upper scope. If @values
+    is empty, then the $context parameter is optional and defaults to the
+    current context (making the call equivalent to a bare "return;") ;
+    otherwise it is mandatory.

 
     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


@@ -282,14 +290,55 @@ FUNCTIONS
 
     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.
 

+  "yield"
+        yield;
+        yield @values, $context;
+
+    Returns @values *from* the context pointed by or just above $context,
+    and immediately restart the program flow at this point. If @values is
+    empty, then the $context parameter is optional and defaults to the
+    current context ; otherwise it is mandatory.
+
+    "yield" differs from "unwind" in that it can target *any* upper scope
+    (besides a "s///e" substitution context) and not necessarily a sub, an
+    eval or a format. Hence you can use it to return values from a "do" or a
+    "map" block :
+
+        my $now = do {
+         local $@;
+         eval { require Time::HiRes } or yield time() => HERE;
+         Time::HiRes::time();
+        };
+
+        my @uniq = map {
+         yield if $seen{$_}++; # returns the empty list from the block
+         ...
+        } @things;
+
+    Like for "unwind", the upper context isn't coerced onto @values. You can
+    use the fifth value returned by "context_info" to handle context
+    coercion.
+
+  "leave"
+        leave;
+        leave @values;
+
+    Immediately returns @values from the current block, whatever it may be
+    (besides a "s///e" substitution context). "leave" is actually a synonym
+    for "unwind HERE", while "leave @values" is a synonym for "yield
+    @values, HERE".
+
+    Like for "yield", you can use the fifth value returned by "context_info"
+    to handle context coercion.
+

   "want_at"
         my $want = want_at;
         my $want = want_at $context;
 
   "want_at"
         my $want = want_at;
         my $want = want_at $context;
 

-    Like "wantarray", but for the subroutine/eval/format at or just above
-    $context.
+    Like "wantarray" in perlfunc, but for the subroutine, eval or format
+    context located at or just above $context.

 
 

-    The previous example can then be "corrected" :
+    It can be used to revise the example showed in "unwind" :

 
         my $num = sub {
          my @a = ('a' .. 'z');
 
         my $num = sub {
          my @a = ('a' .. 'z');


@@ -299,13 +348,57 @@ FUNCTIONS
 
     will rightfully set $num to 26.
 
 
     will rightfully set $num to 26.
 

-  "uplevel $code, @args, $context"
+  "context_info"
+        my ($package, $filename, $line, $subroutine, $hasargs,
+            $wantarray, $evaltext, $is_require, $hints, $bitmask,
+            $hinthash) = context_info $context;
+
+    Gives information about the context denoted by $context, akin to what
+    "caller" in perlfunc provides but not limited only to subroutine, eval
+    and format contexts. When $context is omitted, it defaults to the
+    current context.
+
+    The values returned are, in order :
+
+    *   *(index 0)* : the namespace in use when the context was created ;
+
+    *   *(index 1)* : the name of the file at the point where the context
+        was created ;
+
+    *   *(index 2)* : the line number at the point where the context was
+        created ;
+
+    *   *(index 3)* : the name of the subroutine called for this context, or
+        "undef" if this is not a subroutine context ;
+
+    *   *(index 4)* : a boolean indicating whether a new instance of @_ was
+        set up for this context, or "undef" if this is not a subroutine
+        context ;
+
+    *   *(index 5)* : the context (in the sense of "wantarray" in perlfunc)
+        in which the context (in our sense) is executed ;
+
+    *   *(index 6)* : the contents of the string being compiled for this
+        context, or "undef" if this is not an eval context ;
+
+    *   *(index 7)* : a boolean indicating whether this eval context was
+        created by "require", or "undef" if this is not an eval context ;
+
+    *   *(index 8)* : the value of the lexical hints in use when the context
+        was created ;
+
+    *   *(index 9)* : a bit string representing the warnings in use when the
+        context was created ;
+
+    *   *(index 10)* : a reference to the lexical hints hash in use when the
+        context was created (only on perl 5.10 or greater).
+
+  "uplevel"

         my @ret = uplevel { ...; return @ret };
         my @ret = uplevel { ...; return @ret };

-        my @ret = uplevel { my @args = @_; ...; return @ret } @args;
-        my @ret = uplevel { ... } @args, $context;
+        my @ret = uplevel { my @args = @_; ...; return @ret } @args, $context;

         my @ret = &uplevel($callback, @args, $context);
 
         my @ret = &uplevel($callback, @args, $context);
 

-    Executes the code reference $code with arguments @args as if it were
+    Executes the code reference $callback with arguments @args as if it were

     located at the subroutine stack frame pointed by $context, effectively
     fooling "caller" and "die" into believing that the call actually
     happened higher in the stack. The code is executed in the context of the
     located at the subroutine stack frame pointed by $context, effectively
     fooling "caller" and "die" into believing that the call actually
     happened higher in the stack. The code is executed in the context of the


@@ -324,6 +417,9 @@ FUNCTIONS
         my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
         my $count    = target(1, 2, 4); # $count is 3
 
         my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
         my $count    = target(1, 2, 4); # $count is 3
 

+    Note that if @args is empty, then the $context parameter is optional and
+    defaults to the current context ; otherwise it is mandatory.
+

     Sub::Uplevel also implements a pure-Perl version of "uplevel". Both are
     identical, with the following caveats :
 
     Sub::Uplevel also implements a pure-Perl version of "uplevel". Both are
     identical, with the following caveats :
 


@@ -551,13 +647,15 @@ WORDS
         # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
         ...
 
         # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
         ...
 

-    Where "unwind", "want_at" and "uplevel" point to depending on the $cxt:
+    Where "unwind", "yield", "want_at", "context_info" and "uplevel" point
+    to depending on the $cxt:

 
         sub {
          eval {
           sub {
            {
 
         sub {
          eval {
           sub {
            {

-            unwind @things => $cxt;   # or uplevel { ... } $cxt;
+            unwind @things => $cxt;   # or yield @things => $cxt
+                                      # or uplevel { ... } $cxt

             ...
            }
            ...
             ...
            }
            ...


@@ -573,8 +671,9 @@ WORDS
 
 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",
 
 EXPORT
     The functions "reap", "localize", "localize_elem", "localize_delete",

-    "unwind", "want_at" and "uplevel" are only exported on request, either
-    individually or by the tags ':funcs' and ':all'.
+    "unwind", "yield", "leave", "want_at", "context_info" and "uplevel" 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'.
 
     The constant "SU_THREADSAFE" is also only exported on request,
     individually or by the tags ':consts' and ':all'.


@@ -639,7 +738,12 @@ CAVEATS
     version from Sub::Uplevel.
 
 DEPENDENCIES
     version from Sub::Uplevel.
 
 DEPENDENCIES

-    XSLoader (standard since perl 5.006).
+    perl 5.6.
+
+    A C compiler. This module may happen to build with a C++ compiler as
+    well, but don't rely on it, as no guarantee is made in this regard.
+
+    XSLoader (core since perl 5.006).

 
 SEE ALSO
     "local" in perlfunc, "Temporary Values via local()" in perlsub.
 
 SEE ALSO
     "local" in perlfunc, "Temporary Values via local()" in perlsub.

diff --git a/lib/Scope/Upper.pm b/lib/Scope/Upper.pm
index e36cbca5531e94fe1ce11339f0ed37b39d5746ed..4d44d6cfa27e3b25ce5cdb19dbc2b7ca6092ad5e 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.19
+Version 0.20

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

- $VERSION = '0.19';
+ $VERSION = '0.20';

 }
 
 =head1 SYNOPSIS
 }
 
 =head1 SYNOPSIS