]> git.vpit.fr Git - perl/modules/Scope-Upper.git/blob - README
15bb1ec4605ba4544036305244a377a8aa8cc345
[perl/modules/Scope-Upper.git] / README
1 NAME
2     Scope::Upper - Act on upper scopes.
3
4 VERSION
5     Version 0.32
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 "<vpit at cpan.org>".
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     The reimplementation of a large part of this module for perl 5.24 was
820     provided by David Mitchell. His work was sponsored by the Perl 5 Core
821     Maintenance Grant from The Perl Foundation.
822
823     Thanks to Shawn M. Moore for motivation.
824
825 COPYRIGHT & LICENSE
826     Copyright 2008,2009,2010,2011,2012,2013,2014,2015,2016,2017,2018,2019
827     Vincent Pit, all rights reserved.
828
829     This program is free software; you can redistribute it and/or modify it
830     under the same terms as Perl itself.
831