Do less function calls in Scope::Upper::TestGenerator::gen()

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

diff --git a/README b/README
index faa4a768d5ef3ba30225e7fd74f0e87f3531abe1..e09bd1230a0ccc5c13b1fd17e90188bb56a9a6c5 100644 (file)
--- a/README
+++ b/README
@@ -2,14 +2,17 @@ NAME
     Scope::Upper - Act on upper scopes.
 
 VERSION
     Scope::Upper - Act on upper scopes.
 
 VERSION

-    Version 0.17
+    Version 0.19

 
 SYNOPSIS
     "reap", "localize", "localize_elem", "localize_delete" and "WORDS" :
 
         package Scope;
 
 
 SYNOPSIS
     "reap", "localize", "localize_elem", "localize_delete" and "WORDS" :
 
         package Scope;
 

-        use Scope::Upper qw<reap localize localize_elem localize_delete :words>;
+        use Scope::Upper qw<
+         reap localize localize_elem localize_delete
+         :words
+        >;

 
         sub new {
          my ($class, $name) = @_;
 
         sub new {
          my ($class, $name) = @_;


@@ -51,22 +54,22 @@ SYNOPSIS
         package UserLand;
 
         {
         package UserLand;
 
         {

-         Scope->new("top");      # initializes $UserLand::tag
+         Scope->new("top");    # initializes $UserLand::tag

 
          {
           Scope->catch;
 
          {
           Scope->catch;

-          my $one = 1 + undef;   # prints "top: Use of uninitialized value..."
+          my $one = 1 + undef; # prints "top: Use of uninitialized value..."

 
           {
            Scope->private;
            eval { require Cwd };
 
           {
            Scope->private;
            eval { require Cwd };

-           print $@;             # prints "Can't locate Cwd.pm in @INC (@INC contains:) at..."
-          }
+           print $@;           # prints "Can't locate Cwd.pm in @INC
+          }                    #         (@INC contains:) at..."

 
 

-          require Cwd;           # loads Cwd.pm
+          require Cwd;         # loads Cwd.pm

          }
 
          }
 

-        }                        # prints "top: done"
+        }                      # prints "top: done"

 
     "unwind" and "want_at" :
 
 
     "unwind" and "want_at" :
 


@@ -113,6 +116,28 @@ SYNOPSIS
 
         target('hello'); # "hello from Uplevel::target()"
 
 
         target('hello'); # "hello from Uplevel::target()"
 

+    "uid" and "validate_uid" :
+
+        use Scope::Upper qw<uid validate_uid>;
+
+        my $uid;
+
+        {
+         $uid = uid();
+         {
+          if ($uid eq uid(UP)) { # yes
+           ...
+          }
+          if (validate_uid($uid)) { # yes
+           ...
+          }
+         }
+        }
+
+        if (validate_uid($uid)) { # no
+         ...
+        }
+

 DESCRIPTION
     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:
 DESCRIPTION
     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:


@@ -127,7 +152,9 @@ DESCRIPTION
         which context was in use then with "want_at" ;
 
     *   execute a subroutine in the setting of an upper subroutine stack
         which context was in use then with "want_at" ;
 
     *   execute a subroutine in the setting of an upper subroutine stack

-        frame with "uplevel".
+        frame with "uplevel" ;
+
+    *   uniquely identify contextes with "uid" and "validate_uid".

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


@@ -139,11 +166,18 @@ FUNCTIONS
     which means that you can safely store it at some point and use it when
     needed, and it will still denote the original scope.
 
     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"
+        reap { ... };
+        reap { ... } $context;
+        &reap($callback, $context);
+

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

-  "localize $what, $value, $context"
+  "localize"
+        localize $what, $value;
+        localize $what, $value, $context;
+

     Introduces a "local" delayed to the time of first return into the upper
     scope denoted by $context. $what can be :
 
     Introduces a "local" delayed to the time of first return into the upper
     scope denoted by $context. $what can be :
 


@@ -196,7 +230,10 @@ FUNCTIONS
         implementation detail, this behaviour may change in the future if
         proved harmful.
 
         implementation detail, this behaviour may change in the future if
         proved harmful.
 

-  "localize_elem $what, $key, $value, $context"
+  "localize_elem"
+        localize_elem $what, $key, $value;
+        localize_elem $what, $key, $value, $context;
+

     Introduces a "local $what[$key] = $value" or "local $what{$key} =
     $value" delayed to the time of first return into the upper scope denoted
     by $context. Unlike "localize", $what must be a string and the type of
     Introduces a "local $what[$key] = $value" or "local $what{$key} =
     $value" delayed to the time of first return into the upper scope denoted
     by $context. Unlike "localize", $what must be a string and the type of


@@ -225,7 +262,10 @@ FUNCTIONS
         in the upper scope. It's actually more powerful, as &func won't even
         "exists" anymore. $key is ignored.
 
         in the upper scope. It's actually more powerful, as &func won't even
         "exists" anymore. $key is ignored.
 

-  "unwind @values, $context"
+  "unwind"
+        unwind @values;
+        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
     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


@@ -242,7 +282,10 @@ 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.
 

-  "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", but for the subroutine/eval/format at or just above
     $context.
 


@@ -257,6 +300,11 @@ FUNCTIONS
     will rightfully set $num to 26.
 
   "uplevel $code, @args, $context"
     will rightfully set $num to 26.
 
   "uplevel $code, @args, $context"

+        my @ret = uplevel { ...; return @ret };
+        my @ret = uplevel { my @args = @_; ...; return @ret } @args;
+        my @ret = uplevel { ... } @args, $context;
+        my @ret = &uplevel($callback, @args, $context);
+

     Executes the code reference $code 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
     Executes the code reference $code 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


@@ -325,6 +373,83 @@ FUNCTIONS
     Albeit the three exceptions listed above, it passes all the tests of
     Sub::Uplevel.
 
     Albeit the three exceptions listed above, it passes all the tests of
     Sub::Uplevel.
 

+  "uid"
+        my $uid = uid;
+        my $uid = uid $context;
+
+    Returns an unique identifier (UID) for the context (or dynamic scope)
+    pointed by $context, or for the current context if $context is omitted.
+    This UID will only be valid for the life time of the context it
+    represents, and another UID will be generated next time the same scope
+    is executed.
+
+        my $uid;
+
+        {
+         $uid = uid;
+         if ($uid eq uid()) { # yes, this is the same context
+          ...
+         }
+         {
+          if ($uid eq uid()) { # no, we are one scope below
+           ...
+          }
+          if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
+           ...
+          }
+         }
+        }
+
+        # $uid is now invalid
+
+        {
+         if ($uid eq uid()) { # no, this is another block
+          ...
+         }
+        }
+
+    For example, each loop iteration gets its own UID :
+
+        my %uids;
+
+        for (1 .. 5) {
+         my $uid = uid;
+         $uids{$uid} = $_;
+        }
+
+        # %uids has 5 entries
+
+    The UIDs are not guaranteed to be numbers, so you must use the "eq"
+    operator to compare them.
+
+    To check whether a given UID is valid, you can use the "validate_uid"
+    function.
+
+  "validate_uid"
+        my $is_valid = validate_uid $uid;
+
+    Returns true if and only if $uid is the UID of a currently valid context
+    (that is, it designates a scope that is higher than the current one in
+    the call stack).
+
+        my $uid;
+
+        {
+         $uid = uid();
+         if (validate_uid($uid)) { # yes
+          ...
+         }
+         {
+          if (validate_uid($uid)) { # yes
+           ...
+          }
+         }
+        }
+
+        if (validate_uid($uid)) { # no
+         ...
+        }
+

 CONSTANTS
   "SU_THREADSAFE"
     True iff the module could have been built when thread-safety features.
 CONSTANTS
   "SU_THREADSAFE"
     True iff the module could have been built when thread-safety features.


@@ -332,23 +457,36 @@ CONSTANTS
 WORDS
   Constants
    "TOP"
 WORDS
   Constants
    "TOP"

+        my $top_context = TOP;
+

     Returns the context that currently represents the highest scope.
 
    "HERE"
     Returns the context that currently represents the highest scope.
 
    "HERE"

+        my $current_context = HERE;
+

     The context of the current scope.
 
   Getting a context from a context
     For any of those functions, $from is expected to be a context. When
     omitted, it defaults to the the current context.
 
     The context of the current scope.
 
   Getting a context from a context
     For any of those functions, $from is expected to be a context. When
     omitted, it defaults to the the current context.
 

-   "UP $from"
+   "UP"
+        my $upper_context = UP;
+        my $upper_context = UP $from;
+

     The context of the scope just above $from.
 
     The context of the scope just above $from.
 

-   "SUB $from"
+   "SUB"
+        my $sub_context = SUB;
+        my $sub_context = SUB $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".
 
     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"
+        my $eval_context = EVAL;
+        my $eval_context = EVAL $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".
 
     The context of the closest eval above $from. Note that $from is returned
     if it is already an eval context ; hence "EVAL EVAL == EVAL".
 


@@ -357,10 +495,16 @@ WORDS
     When omitted, it defaults to 0 and those functions return the same
     context as "HERE".
 
     When omitted, it defaults to 0 and those functions return the same
     context as "HERE".
 

-   "SCOPE $level"
+   "SCOPE"
+        my $context = SCOPE;
+        my $context = SCOPE $level;
+

     The $level-th upper context, regardless of its type.
 
     The $level-th upper context, regardless of its type.
 

-   "CALLER $level"
+   "CALLER"
+        my $context = CALLER;
+        my $context = CALLER $level;
+

     The context of the $level-th upper subroutine/eval/format. It kind of
     corresponds to the context represented by "caller $level", but while
     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
     The context of the $level-th upper subroutine/eval/format. It kind of
     corresponds to the context represented by "caller $level", but while
     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to


@@ -375,13 +519,13 @@ WORDS
            {
             reap \&cleanup => $cxt;
             ...
            {
             reap \&cleanup => $cxt;
             ...

-           }     # $cxt = SCOPE(0), or HERE
+           }     # $cxt = SCOPE(0) = HERE

            ...
            ...

-          }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+          }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)

           ...
           ...

-         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+         };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)

          ...
          ...

-        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)

         ...
 
     Where "localize", "localize_elem" and "localize_delete" act depending on
         ...
 
     Where "localize", "localize_elem" and "localize_delete" act depending on


@@ -392,19 +536,19 @@ WORDS
           sub {
            {
             localize '$x' => 1 => $cxt;
           sub {
            {
             localize '$x' => 1 => $cxt;

-            # $cxt = SCOPE(0), or HERE
+            # $cxt = SCOPE(0) = HERE

             ...
            }
             ...
            }

-           # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+           # $cxt = SCOPE(1) = UP = SUB = CALLER(0)

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

-          # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+          # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)

           ...
          };
           ...
          };

-         # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+         # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)

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

-        # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or 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", "want_at" and "uplevel" point to depending on the $cxt:


@@ -413,15 +557,15 @@ WORDS
          eval {
           sub {
            {
          eval {
           sub {
            {

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

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

-          }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
+          }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)

           ...
           ...

-         };      # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1) (*)
+         };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)

          ...
          ...

-        }->();   # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+        }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)

         ...
 
         # (*) Note that uplevel() will croak if you pass that scope frame,
         ...
 
         # (*) Note that uplevel() will croak if you pass that scope frame,


@@ -472,9 +616,16 @@ CAVEATS
     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
     context-related fixes.
 
     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
     context-related fixes.
 

-    Calling "goto" to replace an "uplevel"'d code frame does not work when a
-    custom runloop is used or when debugging flags are set with "perl -D".
-    In those two cases, "uplevel" will look for a "goto &sub" statement in
+    Calling "goto" to replace an "uplevel"'d code frame does not work :
+
+    *   for a "perl" older than the 5.8 series ;
+
+    *   for a "DEBUGGING" "perl" run with debugging flags set (as in "perl
+        -D ...") ;
+
+    *   when the runloop callback is replaced by another module.
+
+    In those three cases, "uplevel" will look for a "goto &sub" statement in

     its callback and, if there is one, throw an exception before executing
     the code.
 
     its callback and, if there is one, throw an exception before executing
     the code.
 


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

-    Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
+    Copyright 2008,2009,2010,2011,2012 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.