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> and L</yield>, 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<want_at>
 344
 345     my $want = want_at;
 346     my $want = want_at $context;
 347
 348 Like C<wantarray>, but for the subroutine/eval/format at or just above C<$context>.
 349
 350 The previous example can then be "corrected" :
 351
 352     my $num = sub {
 353      my @a = ('a' .. 'z');
 354      unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
 355      # not reached
 356     }->();
 357
 358 will rightfully set C<$num> to C<26>.
 359
 360 =head2 C<uplevel>
 361
 362     my @ret = uplevel { ...; return @ret };
 363     my @ret = uplevel { my @args = @_; ...; return @ret } @args, $context;
 364     my @ret = &uplevel($callback, @args, $context);
 365
 366 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.
 367 The code is executed in the context of the C<uplevel> call, and what it returns is returned as-is by C<uplevel>.
 368
 369     sub target {
 370      faker(@_);
 371     }
 372
 373     sub faker {
 374      uplevel {
 375       map { 1 / $_ } @_;
 376      } @_ => CALLER(1);
 377     }
 378
 379     my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
 380     my $count    = target(1, 2, 4); # $count is 3
 381
 382 Note that if C<@args> is empty, then the C<$context> parameter is optional and defaults to the current context ; otherwise it is mandatory.
 383
 384 L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
 385 Both are identical, with the following caveats :
 386
 387 =over 4
 388
 389 =item *
 390
 391 The L<Sub::Uplevel> implementation of C<uplevel> may execute a code reference in the context of B<any> upper stack frame.
 392 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.
 393
 394 =item *
 395
 396 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.
 397 This means that :
 398
 399     eval {
 400      sub {
 401       local $@;
 402       eval {
 403        sub {
 404         uplevel { die 'wut' } CALLER(2); # for Scope::Upper
 405         # uplevel(3, sub { die 'wut' })  # for Sub::Uplevel
 406        }->();
 407       };
 408       print "inner block: $@";
 409       $@ and exit;
 410      }->();
 411     };
 412     print "outer block: $@";
 413
 414 will print "inner block: wut..." with L<Sub::Uplevel> and "outer block: wut..." with L<Scope::Upper>.
 415
 416 =item *
 417
 418 L<Sub::Uplevel> globally overrides the Perl keyword C<caller>, while L<Scope::Upper> does not.
 419
 420 =back
 421
 422 A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
 423
 424     use Scope::Upper;
 425
 426     sub uplevel {
 427      my $frame = shift;
 428      my $code  = shift;
 429      my $cxt   = Scope::Upper::CALLER($frame);
 430      &Scope::Upper::uplevel($code => @_ => $cxt);
 431     }
 432
 433 Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
 434
 435 =head2 C<uid>
 436
 437     my $uid = uid;
 438     my $uid = uid $context;
 439
 440 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.
 441 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.
 442
 443     my $uid;
 444
 445     {
 446      $uid = uid;
 447      if ($uid eq uid()) { # yes, this is the same context
 448       ...
 449      }
 450      {
 451       if ($uid eq uid()) { # no, we are one scope below
 452        ...
 453       }
 454       if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
 455        ...
 456       }
 457      }
 458     }
 459
 460     # $uid is now invalid
 461
 462     {
 463      if ($uid eq uid()) { # no, this is another block
 464       ...
 465      }
 466     }
 467
 468 For example, each loop iteration gets its own UID :
 469
 470     my %uids;
 471
 472     for (1 .. 5) {
 473      my $uid = uid;
 474      $uids{$uid} = $_;
 475     }
 476
 477     # %uids has 5 entries
 478
 479 The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to compare them.
 480
 481 To check whether a given UID is valid, you can use the L</validate_uid> function.
 482
 483 =head2 C<validate_uid>
 484
 485     my $is_valid = validate_uid $uid;
 486
 487 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).
 488
 489     my $uid;
 490
 491     {
 492      $uid = uid();
 493      if (validate_uid($uid)) { # yes
 494       ...
 495      }
 496      {
 497       if (validate_uid($uid)) { # yes
 498        ...
 499       }
 500      }
 501     }
 502
 503     if (validate_uid($uid)) { # no
 504      ...
 505     }
 506
 507 =head1 CONSTANTS
 508
 509 =head2 C<SU_THREADSAFE>
 510
 511 True iff the module could have been built when thread-safety features.
 512
 513 =head1 WORDS
 514
 515 =head2 Constants
 516
 517 =head3 C<TOP>
 518
 519     my $top_context = TOP;
 520
 521 Returns the context that currently represents the highest scope.
 522
 523 =head3 C<HERE>
 524
 525     my $current_context = HERE;
 526
 527 The context of the current scope.
 528
 529 =head2 Getting a context from a context
 530
 531 For any of those functions, C<$from> is expected to be a context.
 532 When omitted, it defaults to the the current context.
 533
 534 =head3 C<UP>
 535
 536     my $upper_context = UP;
 537     my $upper_context = UP $from;
 538
 539 The context of the scope just above C<$from>.
 540
 541 =head3 C<SUB>
 542
 543     my $sub_context = SUB;
 544     my $sub_context = SUB $from;
 545
 546 The context of the closest subroutine above C<$from>.
 547 Note that C<$from> is returned if it is already a subroutine context ; hence C<SUB SUB == SUB>.
 548
 549 =head3 C<EVAL>
 550
 551     my $eval_context = EVAL;
 552     my $eval_context = EVAL $from;
 553
 554 The context of the closest eval above C<$from>.
 555 Note that C<$from> is returned if it is already an eval context ; hence C<EVAL EVAL == EVAL>.
 556
 557 =head2 Getting a context from a level
 558
 559 Here, C<$level> should denote a number of scopes above the current one.
 560 When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
 561
 562 =head3 C<SCOPE>
 563
 564     my $context = SCOPE;
 565     my $context = SCOPE $level;
 566
 567 The C<$level>-th upper context, regardless of its type.
 568
 569 =head3 C<CALLER>
 570
 571     my $context = CALLER;
 572     my $context = CALLER $level;
 573
 574 The context of the C<$level>-th upper subroutine/eval/format.
 575 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.
 576
 577 =head2 Examples
 578
 579 Where L</reap> fires depending on the C<$cxt> :
 580
 581     sub {
 582      eval {
 583       sub {
 584        {
 585         reap \&cleanup => $cxt;
 586         ...
 587        }     # $cxt = SCOPE(0) = HERE
 588        ...
 589       }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 590       ...
 591      };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)
 592      ...
 593     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 594     ...
 595
 596 Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
 597
 598     sub {
 599      eval {
 600       sub {
 601        {
 602         localize '$x' => 1 => $cxt;
 603         # $cxt = SCOPE(0) = HERE
 604         ...
 605        }
 606        # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
 607        ...
 608       }->();
 609       # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
 610       ...
 611      };
 612      # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 613      ...
 614     }->();
 615     # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
 616     ...
 617
 618 Where L</unwind>, L</yield>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
 619
 620     sub {
 621      eval {
 622       sub {
 623        {
 624         unwind @things => $cxt;   # or yield @things => $cxt
 625                                   # or uplevel { ... } $cxt
 626         ...
 627        }
 628        ...
 629       }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
 630       ...
 631      };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
 632      ...
 633     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
 634     ...
 635
 636     # (*) Note that uplevel() will croak if you pass that scope frame,
 637     #     because it cannot target eval scopes.
 638
 639 =head1 EXPORT
 640
 641 The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>,  L</unwind>, L</yield>, L</want_at> and L</uplevel> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
 642
 643 The constant L</SU_THREADSAFE> is also only exported on request, individually or by the tags C<':consts'> and C<':all'>.
 644
 645 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'>.
 646
 647 =cut
 648
 649 use base qw<Exporter>;
 650
 651 our @EXPORT      = ();
 652 our %EXPORT_TAGS = (
 653  funcs  => [ qw<
 654   reap
 655   localize localize_elem localize_delete
 656   unwind yield
 657   want_at
 658   uplevel
 659   uid validate_uid
 660  > ],
 661  words  => [ qw<TOP HERE UP SUB EVAL SCOPE CALLER> ],
 662  consts => [ qw<SU_THREADSAFE> ],
 663 );
 664 our @EXPORT_OK   = map { @$_ } values %EXPORT_TAGS;
 665 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
 666
 667 =head1 CAVEATS
 668
 669 Be careful that local variables are restored in the reverse order in which they were localized.
 670 Consider those examples:
 671
 672     local $x = 0;
 673     {
 674      reap sub { print $x } => HERE;
 675      local $x = 1;
 676      ...
 677     }
 678     # prints '0'
 679     ...
 680     {
 681      local $x = 1;
 682      reap sub { $x = 2 } => HERE;
 683      ...
 684     }
 685     # $x is 0
 686
 687 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>.
 688
 689 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.
 690 This is an hopeless case because C<BEGIN> blocks are executed once while localizing constructs should do their job at each run.
 691 However, it's possible to hook the end of the current scope compilation with L<B::Hooks::EndOfScope>.
 692
 693 Some rare oddities may still happen when running inside the debugger.
 694 It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes.
 695
 696 Calling C<goto> to replace an L</uplevel>'d code frame does not work :
 697
 698 =over 4
 699
 700 =item *
 701
 702 for a C<perl> older than the 5.8 series ;
 703
 704 =item *
 705
 706 for a C<DEBUGGING> C<perl> run with debugging flags set (as in C<perl -D ...>) ;
 707
 708 =item *
 709
 710 when the runloop callback is replaced by another module.
 711
 712 =back
 713
 714 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.
 715
 716 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.
 717 Despite this shortcoming, this XS version of L</uplevel> should still run way faster than the pure-Perl version from L<Sub::Uplevel>.
 718
 719 =head1 DEPENDENCIES
 720
 721 L<XSLoader> (standard since perl 5.006).
 722
 723 =head1 SEE ALSO
 724
 725 L<perlfunc/local>, L<perlsub/"Temporary Values via local()">.
 726
 727 L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
 728
 729 L<Sub::Uplevel>.
 730
 731 L<Continuation::Escape> is a thin wrapper around L<Scope::Upper> that gives you a continuation passing style interface to L</unwind>.
 732 It's easier to use, but it requires you to have control over the scope where you want to return.
 733
 734 L<Scope::Escape>.
 735
 736 =head1 AUTHOR
 737
 738 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
 739
 740 You can contact me by mail or on C<irc.perl.org> (vincent).
 741
 742 =head1 BUGS
 743
 744 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>.
 745 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
 746
 747 =head1 SUPPORT
 748
 749 You can find documentation for this module with the perldoc command.
 750
 751     perldoc Scope::Upper
 752
 753 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scope-Upper>.
 754
 755 =head1 ACKNOWLEDGEMENTS
 756
 757 Inspired by Ricardo Signes.
 758
 759 Thanks to Shawn M. Moore for motivation.
 760
 761 =head1 COPYRIGHT & LICENSE
 762
 763 Copyright 2008,2009,2010,2011,2012 Vincent Pit, all rights reserved.
 764
 765 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
 766
 767 =cut
 768
 769 1; # End of Scope::Upper