README

   1 NAME
   2     Scope::Upper - Act on upper scopes.
   3
   4 VERSION
   5     Version 0.28
   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. If $from points to the
 574     top-level scope in the current stack, then a warning is emitted and
 575     $from is returned (see "DIAGNOSTICS" for details).
 576
 577    "SUB"
 578         my $sub_context = SUB;
 579         my $sub_context = SUB $from;
 580
 581     The context of the closest subroutine above $from. If $from already
 582     designates a subroutine context, then it is returned as-is ; hence "SUB
 583     SUB == SUB". If no subroutine context is present in the call stack, then
 584     a warning is emitted and the current context is returned (see
 585     "DIAGNOSTICS" for details).
 586
 587    "EVAL"
 588         my $eval_context = EVAL;
 589         my $eval_context = EVAL $from;
 590
 591     The context of the closest eval above $from. If $from already designates
 592     an eval context, then it is returned as-is ; hence "EVAL EVAL == EVAL".
 593     If no eval context is present in the call stack, then a warning is
 594     emitted and the current context is returned (see "DIAGNOSTICS" for
 595     details).
 596
 597   Getting a context from a level
 598     Here, $level should denote a number of scopes above the current one.
 599     When omitted, it defaults to 0 and those functions return the same
 600     context as "HERE".
 601
 602    "SCOPE"
 603         my $context = SCOPE;
 604         my $context = SCOPE $level;
 605
 606     The $level-th upper context, regardless of its type. If $level points
 607     above the top-level scope in the current stack, then a warning is
 608     emitted and the top-level context is returned (see "DIAGNOSTICS" for
 609     details).
 610
 611    "CALLER"
 612         my $context = CALLER;
 613         my $context = CALLER $level;
 614
 615     The context of the $level-th upper subroutine/eval/format. It kind of
 616     corresponds to the context represented by "caller $level", but while
 617     e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
 618     the top scope in the current context. If $level points above the
 619     top-level scope in the current stack, then a warning is emitted and the
 620     top-level context is returned (see "DIAGNOSTICS" for details).
 621
 622   Examples
 623     Where "reap" fires depending on the $cxt :
 624
 625         sub {
 626          eval {
 627           sub {
 628            {
 629             reap \&cleanup => $cxt;
 630             ...
 631            }     # $cxt = SCOPE(0) = HERE
 632            ...
 633           }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 634           ...
 635          };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)
 636          ...
 637         }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 638         ...
 639
 640     Where "localize", "localize_elem" and "localize_delete" act depending on
 641     the $cxt :
 642
 643         sub {
 644          eval {
 645           sub {
 646            {
 647             localize '$x' => 1 => $cxt;
 648             # $cxt = SCOPE(0) = HERE
 649             ...
 650            }
 651            # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 652            ...
 653           }->();
 654           # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
 655           ...
 656          };
 657          # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 658          ...
 659         }->();
 660         # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
 661         ...
 662
 663     Where "unwind", "yield", "want_at", "context_info" and "uplevel" point
 664     to depending on the $cxt:
 665
 666         sub {
 667          eval {
 668           sub {
 669            {
 670             unwind @things => $cxt;   # or yield @things => $cxt
 671                                       # or uplevel { ... } $cxt
 672             ...
 673            }
 674            ...
 675           }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
 676           ...
 677          };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
 678          ...
 679         }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 680         ...
 681
 682         # (*) Note that uplevel() will croak if you pass that scope frame,
 683         #     because it cannot target eval scopes.
 684
 685 DIAGNOSTICS
 686   "Cannot target a scope outside of the current stack"
 687     This warning is emitted when "UP", "SCOPE" or "CALLER" end up pointing
 688     to a context that is above the top-level context of the current stack.
 689     It indicates that you tried to go higher than the main scope, or to
 690     point across a "DESTROY" method, a signal handler, an overloaded or tied
 691     method call, a "require" statement or a "sort" callback. In this case,
 692     the resulting context is the highest reachable one.
 693
 694   "No targetable %s scope in the current stack"
 695     This warning is emitted when you ask for an "EVAL" or "SUB" context and
 696     no such scope can be found in the call stack. The resulting context is
 697     the current one.
 698
 699 EXPORT
 700     The functions "reap", "localize", "localize_elem", "localize_delete",
 701     "unwind", "yield", "leave", "want_at", "context_info" and "uplevel" are
 702     only exported on request, either individually or by the tags ':funcs'
 703     and ':all'.
 704
 705     The constant "SU_THREADSAFE" is also only exported on request,
 706     individually or by the tags ':consts' and ':all'.
 707
 708     Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
 709     "CALLER" that are only exported on request, individually or by the tags
 710     ':words' and ':all'.
 711
 712 CAVEATS
 713     It is not possible to act upon a scope that belongs to another perl
 714     'stack', i.e. to target a scope across a "DESTROY" method, a signal
 715     handler, an overloaded or tied method call, a "require" statement or a
 716     "sort" callback.
 717
 718     Be careful that local variables are restored in the reverse order in
 719     which they were localized. Consider those examples:
 720
 721         local $x = 0;
 722         {
 723          reap sub { print $x } => HERE;
 724          local $x = 1;
 725          ...
 726         }
 727         # prints '0'
 728         ...
 729         {
 730          local $x = 1;
 731          reap sub { $x = 2 } => HERE;
 732          ...
 733         }
 734         # $x is 0
 735
 736     The first case is "solved" by moving the "local" before the "reap", and
 737     the second by using "localize" instead of "reap".
 738
 739     The effects of "reap", "localize" and "localize_elem" can't cross
 740     "BEGIN" blocks, hence calling those functions in "import" is deemed to
 741     be useless. This is an hopeless case because "BEGIN" blocks are executed
 742     once while localizing constructs should do their job at each run.
 743     However, it's possible to hook the end of the current scope compilation
 744     with B::Hooks::EndOfScope.
 745
 746     Some rare oddities may still happen when running inside the debugger. It
 747     may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
 748     context-related fixes.
 749
 750     Calling "goto" to replace an "uplevel"'d code frame does not work :
 751
 752     *   for a "perl" older than the 5.8 series ;
 753
 754     *   for a "DEBUGGING" "perl" run with debugging flags set (as in "perl
 755         -D ...") ;
 756
 757     *   when the runloop callback is replaced by another module.
 758
 759     In those three cases, "uplevel" will look for a "goto &sub" statement in
 760     its callback and, if there is one, throw an exception before executing
 761     the code.
 762
 763     Moreover, in order to handle "goto" statements properly, "uplevel"
 764     currently has to suffer a run-time overhead proportional to the size of
 765     the callback in every case (with a small ratio), and proportional to the
 766     size of all the code executed as the result of the "uplevel" call
 767     (including subroutine calls inside the callback) when a "goto" statement
 768     is found in the "uplevel" callback. Despite this shortcoming, this XS
 769     version of "uplevel" should still run way faster than the pure-Perl
 770     version from Sub::Uplevel.
 771
 772     Starting from "perl" 5.19.4, it is unfortunately no longer possible to
 773     reliably throw exceptions from "uplevel"'d code while the debugger is in
 774     use. This may be solved in a future version depending on how the core
 775     evolves.
 776
 777 DEPENDENCIES
 778     perl 5.6.1.
 779
 780     A C compiler. This module may happen to build with a C++ compiler as
 781     well, but don't rely on it, as no guarantee is made in this regard.
 782
 783     XSLoader (core since perl 5.6.0).
 784
 785 SEE ALSO
 786     "local" in perlfunc, "Temporary Values via local()" in perlsub.
 787
 788     Alias, Hook::Scope, Scope::Guard, Guard.
 789
 790     Sub::Uplevel.
 791
 792     Continuation::Escape is a thin wrapper around Scope::Upper that gives
 793     you a continuation passing style interface to "unwind". It's easier to
 794     use, but it requires you to have control over the scope where you want
 795     to return.
 796
 797     Scope::Escape.
 798
 799 AUTHOR
 800     Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
 801
 802     You can contact me by mail or on "irc.perl.org" (vincent).
 803
 804 BUGS
 805     Please report any bugs or feature requests to "bug-scope-upper at
 806     rt.cpan.org", or through the web interface at
 807     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
 808     notified, and then you'll automatically be notified of progress on your
 809     bug as I make changes.
 810
 811 SUPPORT
 812     You can find documentation for this module with the perldoc command.
 813
 814         perldoc Scope::Upper
 815
 816 ACKNOWLEDGEMENTS
 817     Inspired by Ricardo Signes.
 818
 819     Thanks to Shawn M. Moore for motivation.
 820
 821 COPYRIGHT & LICENSE
 822     Copyright 2008,2009,2010,2011,2012,2013,2014,2015 Vincent Pit, all
 823     rights reserved.
 824
 825     This program is free software; you can redistribute it and/or modify it
 826     under the same terms as Perl itself.
 827