README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.26
   6
   7 SYNOPSIS
   8     "reap", "localize", "localize_elem", "localize_delete" and "WORDS" :
   9
  10         package Scope;
  11
  12         use Scope::Upper qw<
  13          reap localize localize_elem localize_delete
  14          :words
  15         >;
  16
  17         sub new {
  18          my ($class, $name) = @_;
  19
  20          localize '$tag' => bless({ name => $name }, $class) => UP;
  21
  22          reap { print Scope->tag->name, ": end\n" } UP;
  23         }
  24
  25         # Get the tag stored in the caller namespace
  26         sub tag {
  27          my $l   = 0;
  28          my $pkg = __PACKAGE__;
  29          $pkg    = caller $l++ while $pkg eq __PACKAGE__;
  30
  31          no strict 'refs';
  32          ${$pkg . '::tag'};
  33         }
  34
  35         sub name { shift->{name} }
  36
  37         # Locally capture warnings and reprint them with the name prefixed
  38         sub catch {
  39          localize_elem '%SIG', '__WARN__' => sub {
  40           print Scope->tag->name, ': ', @_;
  41          } => UP;
  42         }
  43
  44         # Locally clear @INC
  45         sub private {
  46          for (reverse 0 .. $#INC) {
  47           # First UP is the for loop, second is the sub boundary
  48           localize_delete '@INC', $_ => UP UP;
  49          }
  50         }
  51
  52         ...
  53
  54         package UserLand;
  55
  56         {
  57          Scope->new("top");    # initializes $UserLand::tag
  58
  59          {
  60           Scope->catch;
  61           my $one = 1 + undef; # prints "top: Use of uninitialized value..."
  62
  63           {
  64            Scope->private;
  65            eval { require Cwd };
  66            print $@;           # prints "Can't locate Cwd.pm in @INC
  67           }                    #         (@INC contains:) at..."
  68
  69           require Cwd;         # loads Cwd.pm
  70          }
  71
  72         }                      # prints "top: done"
  73
  74     "unwind" and "want_at" :
  75
  76         package Try;
  77
  78         use Scope::Upper qw<unwind want_at :words>;
  79
  80         sub try (&) {
  81          my @result = shift->();
  82          my $cx = SUB UP; # Point to the sub above this one
  83          unwind +(want_at($cx) ? @result : scalar @result) => $cx;
  84         }
  85
  86         ...
  87
  88         sub zap {
  89          try {
  90           my @things = qw<a b c>;
  91           return @things; # returns to try() and then outside zap()
  92           # not reached
  93          };
  94          # not reached
  95         }
  96
  97         my @stuff = zap(); # @stuff contains qw<a b c>
  98         my $stuff = zap(); # $stuff contains 3
  99
 100     "uplevel" :
 101
 102         package Uplevel;
 103
 104         use Scope::Upper qw<uplevel CALLER>;
 105
 106         sub target {
 107          faker(@_);
 108         }
 109
 110         sub faker {
 111          uplevel {
 112           my $sub = (caller 0)[3];
 113           print "$_[0] from $sub()";
 114          } @_ => CALLER(1);
 115         }
 116
 117         target('hello'); # "hello from Uplevel::target()"
 118
 119     "uid" and "validate_uid" :
 120
 121         use Scope::Upper qw<uid validate_uid>;
 122
 123         my $uid;
 124
 125         {
 126          $uid = uid();
 127          {
 128           if ($uid eq uid(UP)) { # yes
 129            ...
 130           }
 131           if (validate_uid($uid)) { # yes
 132            ...
 133           }
 134          }
 135         }
 136
 137         if (validate_uid($uid)) { # no
 138          ...
 139         }
 140
 141 DESCRIPTION
 142     This module lets you defer actions *at run-time* that will take place
 143     when the control flow returns into an upper scope. Currently, you can:
 144
 145     *   hook an upper scope end with "reap" ;
 146
 147     *   localize variables, array/hash values or deletions of elements in
 148         higher contexts with respectively "localize", "localize_elem" and
 149         "localize_delete" ;
 150
 151     *   return values immediately to an upper level with "unwind", "yield"
 152         and "leave" ;
 153
 154     *   gather information about an upper context with "want_at" and
 155         "context_info" ;
 156
 157     *   execute a subroutine in the setting of an upper subroutine stack
 158         frame with "uplevel" ;
 159
 160     *   uniquely identify contexts with "uid" and "validate_uid".
 161
 162 FUNCTIONS
 163     In all those functions, $context refers to the target scope.
 164
 165     You have to use one or a combination of "WORDS" to build the $context
 166     passed to these functions. This is needed in order to ensure that the
 167     module still works when your program is ran in the debugger. The only
 168     thing you can assume is that it is an *absolute* indicator of the frame,
 169     which means that you can safely store it at some point and use it when
 170     needed, and it will still denote the original scope.
 171
 172   "reap"
 173         reap { ... };
 174         reap { ... } $context;
 175         &reap($callback, $context);
 176
 177     Adds a destructor that calls $callback (in void context) when the upper
 178     scope represented by $context ends.
 179
 180   "localize"
 181         localize $what, $value;
 182         localize $what, $value, $context;
 183
 184     Introduces a "local" delayed to the time of first return into the upper
 185     scope denoted by $context. $what can be :
 186
 187     *   A glob, in which case $value can either be a glob or a reference.
 188         "localize" follows then the same syntax as "local *x = $value". For
 189         example, if $value is a scalar reference, then the "SCALAR" slot of
 190         the glob will be set to $$value - just like "local *x = \1" sets $x
 191         to 1.
 192
 193     *   A string beginning with a sigil, representing the symbol to localize
 194         and to assign to. If the sigil is '$', "localize" follows the same
 195         syntax as "local $x = $value", i.e. $value isn't dereferenced. For
 196         example,
 197
 198             localize '$x', \'foo' => HERE;
 199
 200         will set $x to a reference to the string 'foo'. Other sigils ('@',
 201         '%', '&' and '*') require $value to be a reference of the
 202         corresponding type.
 203
 204         When the symbol is given by a string, it is resolved when the actual
 205         localization takes place and not when "localize" is called. Thus, if
 206         the symbol name is not qualified, it will refer to the variable in
 207         the package where the localization actually takes place and not in
 208         the one where the "localize" call was compiled. For example,
 209
 210             {
 211              package Scope;
 212              sub new { localize '$tag', $_[0] => UP }
 213             }
 214
 215             {
 216              package Tool;
 217              {
 218               Scope->new;
 219               ...
 220              }
 221             }
 222
 223         will localize $Tool::tag and not $Scope::tag. If you want the other
 224         behaviour, you just have to specify $what as a glob or a qualified
 225         name.
 226
 227         Note that if $what is a string denoting a variable that wasn't
 228         declared beforehand, the relevant slot will be vivified as needed
 229         and won't be deleted from the glob when the localization ends. This
 230         situation never arises with "local" because it only compiles when
 231         the localized variable is already declared. Although I believe it
 232         shouldn't be a problem as glob slots definedness is pretty much an
 233         implementation detail, this behaviour may change in the future if
 234         proved harmful.
 235
 236   "localize_elem"
 237         localize_elem $what, $key, $value;
 238         localize_elem $what, $key, $value, $context;
 239
 240     Introduces a "local $what[$key] = $value" or "local $what{$key} =
 241     $value" delayed to the time of first return into the upper scope denoted
 242     by $context. Unlike "localize", $what must be a string and the type of
 243     localization is inferred from its sigil. The two only valid types are
 244     array and hash ; for anything besides those, "localize_elem" will throw
 245     an exception. $key is either an array index or a hash key, depending of
 246     which kind of variable you localize.
 247
 248     If $what is a string pointing to an undeclared variable, the variable
 249     will be vivified as soon as the localization occurs and emptied when it
 250     ends, although it will still exist in its glob.
 251
 252   "localize_delete"
 253         localize_delete $what, $key;
 254         localize_delete $what, $key, $context;
 255
 256     Introduces the deletion of a variable or an array/hash element delayed
 257     to the time of first return into the upper scope denoted by $context.
 258     $what can be:
 259
 260     *   A glob, in which case $key is ignored and the call is equivalent to
 261         "local *x".
 262
 263     *   A string beginning with '@' or '%', for which the call is equivalent
 264         to respectively "local $a[$key]; delete $a[$key]" and "local
 265         $h{$key}; delete $h{$key}".
 266
 267     *   A string beginning with '&', which more or less does "undef &func"
 268         in the upper scope. It's actually more powerful, as &func won't even
 269         "exists" anymore. $key is ignored.
 270
 271   "unwind"
 272         unwind;
 273         unwind @values, $context;
 274
 275     Returns @values *from* the subroutine, eval or format context pointed by
 276     or just above $context, and immediately restarts the program flow at
 277     this point - thus effectively returning @values to an upper scope. If
 278     @values is empty, then the $context parameter is optional and defaults
 279     to the current context (making the call equivalent to a bare "return;")
 280     ; otherwise it is mandatory.
 281
 282     The upper context isn't coerced onto @values, which is hence always
 283     evaluated in list context. This means that
 284
 285         my $num = sub {
 286          my @a = ('a' .. 'z');
 287          unwind @a => HERE;
 288          # not reached
 289         }->();
 290
 291     will set $num to 'z'. You can use "want_at" to handle these cases.
 292
 293   "yield"
 294         yield;
 295         yield @values, $context;
 296
 297     Returns @values *from* the context pointed by or just above $context,
 298     and immediately restarts the program flow at this point. If @values is
 299     empty, then the $context parameter is optional and defaults to the
 300     current context ; otherwise it is mandatory.
 301
 302     "yield" differs from "unwind" in that it can target *any* upper scope
 303     (besides a "s///e" substitution context) and not necessarily a sub, an
 304     eval or a format. Hence you can use it to return values from a "do" or a
 305     "map" block :
 306
 307         my $now = do {
 308          local $@;
 309          eval { require Time::HiRes } or yield time() => HERE;
 310          Time::HiRes::time();
 311         };
 312
 313         my @uniq = map {
 314          yield if $seen{$_}++; # returns the empty list from the block
 315          ...
 316         } @things;
 317
 318     Like for "unwind", the upper context isn't coerced onto @values. You can
 319     use the fifth value returned by "context_info" to handle context
 320     coercion.
 321
 322   "leave"
 323         leave;
 324         leave @values;
 325
 326     Immediately returns @values from the current block, whatever it may be
 327     (besides a "s///e" substitution context). "leave" is actually a synonym
 328     for "yield HERE", while "leave @values" is a synonym for "yield @values,
 329     HERE".
 330
 331     Like for "yield", you can use the fifth value returned by "context_info"
 332     to handle context coercion.
 333
 334   "want_at"
 335         my $want = want_at;
 336         my $want = want_at $context;
 337
 338     Like "wantarray" in perlfunc, but for the subroutine, eval or format
 339     context located at or just above $context.
 340
 341     It can be used to revise the example showed in "unwind" :
 342
 343         my $num = sub {
 344          my @a = ('a' .. 'z');
 345          unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
 346          # not reached
 347         }->();
 348
 349     will rightfully set $num to 26.
 350
 351   "context_info"
 352         my ($package, $filename, $line, $subroutine, $hasargs,
 353             $wantarray, $evaltext, $is_require, $hints, $bitmask,
 354             $hinthash) = context_info $context;
 355
 356     Gives information about the context denoted by $context, akin to what
 357     "caller" in perlfunc provides but not limited only to subroutine, eval
 358     and format contexts. When $context is omitted, it defaults to the
 359     current context.
 360
 361     The returned values are, in order :
 362
 363     *   *(index 0)* : the namespace in use when the context was created ;
 364
 365     *   *(index 1)* : the name of the file at the point where the context
 366         was created ;
 367
 368     *   *(index 2)* : the line number at the point where the context was
 369         created ;
 370
 371     *   *(index 3)* : the name of the subroutine called for this context, or
 372         "undef" if this is not a subroutine context ;
 373
 374     *   *(index 4)* : a boolean indicating whether a new instance of @_ was
 375         set up for this context, or "undef" if this is not a subroutine
 376         context ;
 377
 378     *   *(index 5)* : the context (in the sense of "wantarray" in perlfunc)
 379         in which the context (in our sense) is executed ;
 380
 381     *   *(index 6)* : the contents of the string being compiled for this
 382         context, or "undef" if this is not an eval context ;
 383
 384     *   *(index 7)* : a boolean indicating whether this eval context was
 385         created by "require", or "undef" if this is not an eval context ;
 386
 387     *   *(index 8)* : the value of the lexical hints in use when the context
 388         was created ;
 389
 390     *   *(index 9)* : a bit string representing the warnings in use when the
 391         context was created ;
 392
 393     *   *(index 10)* : a reference to the lexical hints hash in use when the
 394         context was created (only on perl 5.10 or greater).
 395
 396   "uplevel"
 397         my @ret = uplevel { ...; return @ret };
 398         my @ret = uplevel { my @args = @_; ...; return @ret } @args, $context;
 399         my @ret = &uplevel($callback, @args, $context);
 400
 401     Executes the code reference $callback with arguments @args as if it were
 402     located at the subroutine stack frame pointed by $context, effectively
 403     fooling "caller" and "die" into believing that the call actually
 404     happened higher in the stack. The code is executed in the context of the
 405     "uplevel" call, and what it returns is returned as-is by "uplevel".
 406
 407         sub target {
 408          faker(@_);
 409         }
 410
 411         sub faker {
 412          uplevel {
 413           map { 1 / $_ } @_;
 414          } @_ => CALLER(1);
 415         }
 416
 417         my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
 418         my $count    = target(1, 2, 4); # $count is 3
 419
 420     Note that if @args is empty, then the $context parameter is optional and
 421     defaults to the current context ; otherwise it is mandatory.
 422
 423     Sub::Uplevel also implements a pure-Perl version of "uplevel". Both are
 424     identical, with the following caveats :
 425
 426     *   The Sub::Uplevel implementation of "uplevel" may execute a code
 427         reference in the context of any upper stack frame. The Scope::Upper
 428         version can only uplevel to a subroutine stack frame, and will croak
 429         if you try to target an "eval" or a format.
 430
 431     *   Exceptions thrown from the code called by this version of "uplevel"
 432         will not be caught by "eval" blocks between the target frame and the
 433         uplevel call, while they will for Sub::Uplevel's version. This means
 434         that :
 435
 436             eval {
 437              sub {
 438               local $@;
 439               eval {
 440                sub {
 441                 uplevel { die 'wut' } CALLER(2); # for Scope::Upper
 442                 # uplevel(3, sub { die 'wut' })  # for Sub::Uplevel
 443                }->();
 444               };
 445               print "inner block: $@";
 446               $@ and exit;
 447              }->();
 448             };
 449             print "outer block: $@";
 450
 451         will print "inner block: wut..." with Sub::Uplevel and "outer block:
 452         wut..." with Scope::Upper.
 453
 454     *   Sub::Uplevel globally overrides the Perl keyword "caller", while
 455         Scope::Upper does not.
 456
 457     A simple wrapper lets you mimic the interface of "uplevel" in
 458     Sub::Uplevel :
 459
 460         use Scope::Upper;
 461
 462         sub uplevel {
 463          my $frame = shift;
 464          my $code  = shift;
 465          my $cxt   = Scope::Upper::CALLER($frame);
 466          &Scope::Upper::uplevel($code => @_ => $cxt);
 467         }
 468
 469     Albeit the three exceptions listed above, it passes all the tests of
 470     Sub::Uplevel.
 471
 472   "uid"
 473         my $uid = uid;
 474         my $uid = uid $context;
 475
 476     Returns an unique identifier (UID) for the context (or dynamic scope)
 477     pointed by $context, or for the current context if $context is omitted.
 478     This UID will only be valid for the life time of the context it
 479     represents, and another UID will be generated next time the same scope
 480     is executed.
 481
 482         my $uid;
 483
 484         {
 485          $uid = uid;
 486          if ($uid eq uid()) { # yes, this is the same context
 487           ...
 488          }
 489          {
 490           if ($uid eq uid()) { # no, we are one scope below
 491            ...
 492           }
 493           if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
 494            ...
 495           }
 496          }
 497         }
 498
 499         # $uid is now invalid
 500
 501         {
 502          if ($uid eq uid()) { # no, this is another block
 503           ...
 504          }
 505         }
 506
 507     For example, each loop iteration gets its own UID :
 508
 509         my %uids;
 510
 511         for (1 .. 5) {
 512          my $uid = uid;
 513          $uids{$uid} = $_;
 514         }
 515
 516         # %uids has 5 entries
 517
 518     The UIDs are not guaranteed to be numbers, so you must use the "eq"
 519     operator to compare them.
 520
 521     To check whether a given UID is valid, you can use the "validate_uid"
 522     function.
 523
 524   "validate_uid"
 525         my $is_valid = validate_uid $uid;
 526
 527     Returns true if and only if $uid is the UID of a currently valid context
 528     (that is, it designates a scope that is higher than the current one in
 529     the call stack).
 530
 531         my $uid;
 532
 533         {
 534          $uid = uid();
 535          if (validate_uid($uid)) { # yes
 536           ...
 537          }
 538          {
 539           if (validate_uid($uid)) { # yes
 540            ...
 541           }
 542          }
 543         }
 544
 545         if (validate_uid($uid)) { # no
 546          ...
 547         }
 548
 549 CONSTANTS
 550   "SU_THREADSAFE"
 551     True iff the module could have been built when thread-safety features.
 552
 553 WORDS
 554   Constants
 555    "TOP"
 556         my $top_context = TOP;
 557
 558     Returns the context that currently represents the highest scope.
 559
 560    "HERE"
 561         my $current_context = HERE;
 562
 563     The context of the current scope.
 564
 565   Getting a context from a context
 566     For any of those functions, $from is expected to be a context. When
 567     omitted, it defaults to the current context.
 568
 569    "UP"
 570         my $upper_context = UP;
 571         my $upper_context = UP $from;
 572
 573     The context of the scope just above $from.
 574
 575    "SUB"
 576         my $sub_context = SUB;
 577         my $sub_context = SUB $from;
 578
 579     The context of the closest subroutine above $from. Note that $from is
 580     returned if it is already a subroutine context ; hence "SUB SUB == SUB".
 581
 582    "EVAL"
 583         my $eval_context = EVAL;
 584         my $eval_context = EVAL $from;
 585
 586     The context of the closest eval above $from. Note that $from is returned
 587     if it is already an eval context ; hence "EVAL EVAL == EVAL".
 588
 589   Getting a context from a level
 590     Here, $level should denote a number of scopes above the current one.
 591     When omitted, it defaults to 0 and those functions return the same
 592     context as "HERE".
 593
 594    "SCOPE"
 595         my $context = SCOPE;
 596         my $context = SCOPE $level;
 597
 598     The $level-th upper context, regardless of its type.
 599
 600    "CALLER"
 601         my $context = CALLER;
 602         my $context = CALLER $level;
 603
 604     The context of the $level-th upper subroutine/eval/format. It kind of
 605     corresponds to the context represented by "caller $level", but while
 606     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
 607     the top scope in the current context.
 608
 609   Examples
 610     Where "reap" fires depending on the $cxt :
 611
 612         sub {
 613          eval {
 614           sub {
 615            {
 616             reap \&cleanup => $cxt;
 617             ...
 618            }     # $cxt = SCOPE(0) = HERE
 619            ...
 620           }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 621           ...
 622          };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)
 623          ...
 624         }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 625         ...
 626
 627     Where "localize", "localize_elem" and "localize_delete" act depending on
 628     the $cxt :
 629
 630         sub {
 631          eval {
 632           sub {
 633            {
 634             localize '$x' => 1 => $cxt;
 635             # $cxt = SCOPE(0) = HERE
 636             ...
 637            }
 638            # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 639            ...
 640           }->();
 641           # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
 642           ...
 643          };
 644          # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 645          ...
 646         }->();
 647         # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
 648         ...
 649
 650     Where "unwind", "yield", "want_at", "context_info" and "uplevel" point
 651     to depending on the $cxt:
 652
 653         sub {
 654          eval {
 655           sub {
 656            {
 657             unwind @things => $cxt;   # or yield @things => $cxt
 658                                       # or uplevel { ... } $cxt
 659             ...
 660            }
 661            ...
 662           }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
 663           ...
 664          };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
 665          ...
 666         }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 667         ...
 668
 669         # (*) Note that uplevel() will croak if you pass that scope frame,
 670         #     because it cannot target eval scopes.
 671
 672 EXPORT
 673     The functions "reap", "localize", "localize_elem", "localize_delete",
 674     "unwind", "yield", "leave", "want_at", "context_info" and "uplevel" are
 675     only exported on request, either individually or by the tags ':funcs'
 676     and ':all'.
 677
 678     The constant "SU_THREADSAFE" is also only exported on request,
 679     individually or by the tags ':consts' and ':all'.
 680
 681     Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
 682     "CALLER" that are only exported on request, individually or by the tags
 683     ':words' and ':all'.
 684
 685 CAVEATS
 686     Be careful that local variables are restored in the reverse order in
 687     which they were localized. Consider those examples:
 688
 689         local $x = 0;
 690         {
 691          reap sub { print $x } => HERE;
 692          local $x = 1;
 693          ...
 694         }
 695         # prints '0'
 696         ...
 697         {
 698          local $x = 1;
 699          reap sub { $x = 2 } => HERE;
 700          ...
 701         }
 702         # $x is 0
 703
 704     The first case is "solved" by moving the "local" before the "reap", and
 705     the second by using "localize" instead of "reap".
 706
 707     The effects of "reap", "localize" and "localize_elem" can't cross
 708     "BEGIN" blocks, hence calling those functions in "import" is deemed to
 709     be useless. This is an hopeless case because "BEGIN" blocks are executed
 710     once while localizing constructs should do their job at each run.
 711     However, it's possible to hook the end of the current scope compilation
 712     with B::Hooks::EndOfScope.
 713
 714     Some rare oddities may still happen when running inside the debugger. It
 715     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
 716     context-related fixes.
 717
 718     Calling "goto" to replace an "uplevel"'d code frame does not work :
 719
 720     *   for a "perl" older than the 5.8 series ;
 721
 722     *   for a "DEBUGGING" "perl" run with debugging flags set (as in "perl
 723         -D ...") ;
 724
 725     *   when the runloop callback is replaced by another module.
 726
 727     In those three cases, "uplevel" will look for a "goto &sub" statement in
 728     its callback and, if there is one, throw an exception before executing
 729     the code.
 730
 731     Moreover, in order to handle "goto" statements properly, "uplevel"
 732     currently has to suffer a run-time overhead proportional to the size of
 733     the callback in every case (with a small ratio), and proportional to the
 734     size of all the code executed as the result of the "uplevel" call
 735     (including subroutine calls inside the callback) when a "goto" statement
 736     is found in the "uplevel" callback. Despite this shortcoming, this XS
 737     version of "uplevel" should still run way faster than the pure-Perl
 738     version from Sub::Uplevel.
 739
 740 DEPENDENCIES
 741     perl 5.6.1.
 742
 743     A C compiler. This module may happen to build with a C++ compiler as
 744     well, but don't rely on it, as no guarantee is made in this regard.
 745
 746     XSLoader (core since perl 5.6.0).
 747
 748 SEE ALSO
 749     "local" in perlfunc, "Temporary Values via local()" in perlsub.
 750
 751     Alias, Hook::Scope, Scope::Guard, Guard.
 752
 753     Sub::Uplevel.
 754
 755     Continuation::Escape is a thin wrapper around Scope::Upper that gives
 756     you a continuation passing style interface to "unwind". It's easier to
 757     use, but it requires you to have control over the scope where you want
 758     to return.
 759
 760     Scope::Escape.
 761
 762 AUTHOR
 763     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 764
 765     You can contact me by mail or on "irc.perl.org" (vincent).
 766
 767 BUGS
 768     Please report any bugs or feature requests to "bug-scope-upper at
 769     rt.cpan.org", or through the web interface at
 770     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 771     notified, and then you'll automatically be notified of progress on your
 772     bug as I make changes.
 773
 774 SUPPORT
 775     You can find documentation for this module with the perldoc command.
 776
 777         perldoc Scope::Upper
 778
 779     Tests code coverage report is available at
 780     <http://www.profvince.com/perl/cover/Scope-Upper>.
 781
 782 ACKNOWLEDGEMENTS
 783     Inspired by Ricardo Signes.
 784
 785     Thanks to Shawn M. Moore for motivation.
 786
 787 COPYRIGHT & LICENSE
 788     Copyright 2008,2009,2010,2011,2012,2013,2014,2015 Vincent Pit, all
 789     rights reserved.
 790
 791     This program is free software; you can redistribute it and/or modify it
 792     under the same terms as Perl itself.
 793