lib/Scope/Upper.pm

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