]> git.vpit.fr Git - perl/modules/Scope-Upper.git/blob - Upper.pm
868052da3a3f52224bd41166d899dac70fb9f00c
[perl/modules/Scope-Upper.git] / 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.22
13
14 =cut
15
16 our $VERSION;
17 BEGIN {
18  $VERSION = '0.22';
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> ;
174
175 =item *
176
177 gather information about an upper context with L</want_at> and L</context_info> ;
178
179 =item *
180
181 execute a subroutine in the setting of an upper subroutine stack frame with L</uplevel> ;
182
183 =item *
184
185 uniquely identify contexts with L</uid> and L</validate_uid>.
186
187 =back
188
189 =head1 FUNCTIONS
190
191 In all those functions, C<$context> refers to the target scope.
192
193 You have to use one or a combination of L</WORDS> to build the C<$context> passed to these functions.
194 This is needed in order to ensure that the module still works when your program is ran in the debugger.
195 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.
196
197 =cut
198
199 BEGIN {
200  require XSLoader;
201  XSLoader::load(__PACKAGE__, $VERSION);
202 }
203
204 =head2 C<reap>
205
206     reap { ... };
207     reap { ... } $context;
208     &reap($callback, $context);
209
210 Adds a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends.
211
212 =head2 C<localize>
213
214     localize $what, $value;
215     localize $what, $value, $context;
216
217 Introduces a C<local> delayed to the time of first return into the upper scope denoted by C<$context>.
218 C<$what> can be :
219
220 =over 4
221
222 =item *
223
224 A glob, in which case C<$value> can either be a glob or a reference.
225 L</localize> follows then the same syntax as C<local *x = $value>.
226 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>.
227
228 =item *
229
230 A string beginning with a sigil, representing the symbol to localize and to assign to.
231 If the sigil is C<'$'>, L</localize> follows the same syntax as C<local $x = $value>, i.e. C<$value> isn't dereferenced.
232 For example,
233
234     localize '$x', \'foo' => HERE;
235
236 will set C<$x> to a reference to the string C<'foo'>.
237 Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type.
238
239 When the symbol is given by a string, it is resolved when the actual localization takes place and not when L</localize> is called.
240 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.
241 For example,
242
243     {
244      package Scope;
245      sub new { localize '$tag', $_[0] => UP }
246     }
247
248     {
249      package Tool;
250      {
251       Scope->new;
252       ...
253      }
254     }
255
256 will localize C<$Tool::tag> and not C<$Scope::tag>.
257 If you want the other behaviour, you just have to specify C<$what> as a glob or a qualified name.
258
259 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.
260 This situation never arises with C<local> because it only compiles when the localized variable is already declared.
261 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.
262
263 =back
264
265 =head2 C<localize_elem>
266
267     localize_elem $what, $key, $value;
268     localize_elem $what, $key, $value, $context;
269
270 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>.
271 Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
272 The two only valid types are array and hash ; for anything besides those, L</localize_elem> will throw an exception.
273 C<$key> is either an array index or a hash key, depending of which kind of variable you localize.
274
275 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.
276
277 =head2 C<localize_delete>
278
279     localize_delete $what, $key;
280     localize_delete $what, $key, $context;
281
282 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>.
283 C<$what> can be:
284
285 =over 4
286
287 =item *
288
289 A glob, in which case C<$key> is ignored and the call is equivalent to C<local *x>.
290
291 =item *
292
293 A string beginning with C<'@'> or C<'%'>, for which the call is equivalent to respectively C<local $a[$key]; delete $a[$key]> and C<local $h{$key}; delete $h{$key}>.
294
295 =item *
296
297 A string beginning with C<'&'>, which more or less does C<undef &func> in the upper scope.
298 It's actually more powerful, as C<&func> won't even C<exists> anymore.
299 C<$key> is ignored.
300
301 =back
302
303 =head2 C<unwind>
304
305     unwind;
306     unwind @values, $context;
307
308 Returns C<@values> I<from> the subroutine, eval or format context pointed by or just above C<$context>, and immediately restarts the program flow at this point - thus effectively returning C<@values> to an upper scope.
309 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.
310
311 The upper context isn't coerced onto C<@values>, which is hence always evaluated in list context.
312 This means that
313
314     my $num = sub {
315      my @a = ('a' .. 'z');
316      unwind @a => HERE;
317      # not reached
318     }->();
319
320 will set C<$num> to C<'z'>.
321 You can use L</want_at> to handle these cases.
322
323 =head2 C<yield>
324
325     yield;
326     yield @values, $context;
327
328 Returns C<@values> I<from> the context pointed by or just above C<$context>, and immediately restarts the program flow at this point.
329 If C<@values> is empty, then the C<$context> parameter is optional and defaults to the current context ; otherwise it is mandatory.
330
331 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.
332 Hence you can use it to return values from a C<do> or a C<map> block :
333
334     my $now = do {
335      local $@;
336      eval { require Time::HiRes } or yield time() => HERE;
337      Time::HiRes::time();
338     };
339
340     my @uniq = map {
341      yield if $seen{$_}++; # returns the empty list from the block
342      ...
343     } @things;
344
345 Like for L</unwind>, the upper context isn't coerced onto C<@values>.
346 You can use the fifth value returned by L</context_info> to handle context coercion.
347
348 =head2 C<leave>
349
350     leave;
351     leave @values;
352
353 Immediately returns C<@values> from the current block, whatever it may be (besides a C<s///e> substitution context).
354 C<leave> is actually a synonym for C<yield HERE>, while C<leave @values> is a synonym for C<yield @values, HERE>.
355
356 Like for L</yield>, you can use the fifth value returned by L</context_info> to handle context coercion.
357
358 =head2 C<want_at>
359
360     my $want = want_at;
361     my $want = want_at $context;
362
363 Like L<perlfunc/wantarray>, but for the subroutine, eval or format context located at or just above C<$context>.
364
365 It can be used to revise the example showed in L</unwind> :
366
367     my $num = sub {
368      my @a = ('a' .. 'z');
369      unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
370      # not reached
371     }->();
372
373 will rightfully set C<$num> to C<26>.
374
375 =head2 C<context_info>
376
377     my ($package, $filename, $line, $subroutine, $hasargs,
378         $wantarray, $evaltext, $is_require, $hints, $bitmask,
379         $hinthash) = context_info $context;
380
381 Gives information about the context denoted by C<$context>, akin to what L<perlfunc/caller> provides but not limited only to subroutine, eval and format contexts.
382 When C<$context> is omitted, it defaults to the current context.
383
384 The returned values are, in order :
385
386 =over 4
387
388 =item *
389
390 I<(index 0)> : the namespace in use when the context was created ;
391
392 =item *
393
394 I<(index 1)> : the name of the file at the point where the context was created ;
395
396 =item *
397
398 I<(index 2)> : the line number at the point where the context was created ;
399
400 =item *
401
402 I<(index 3)> : the name of the subroutine called for this context, or C<undef> if this is not a subroutine context ;
403
404 =item *
405
406 I<(index 4)> : a boolean indicating whether a new instance of C<@_> was set up for this context, or C<undef> if this is not a subroutine context ;
407
408 =item *
409
410 I<(index 5)> : the context (in the sense of L<perlfunc/wantarray>) in which the context (in our sense) is executed ;
411
412 =item *
413
414 I<(index 6)> : the contents of the string being compiled for this context, or C<undef> if this is not an eval context ;
415
416 =item *
417
418 I<(index 7)> : a boolean indicating whether this eval context was created by C<require>, or C<undef> if this is not an eval context ;
419
420 =item *
421
422 I<(index 8)> : the value of the lexical hints in use when the context was created ;
423
424 =item *
425
426 I<(index 9)> : a bit string representing the warnings in use when the context was created ;
427
428 =item *
429
430 I<(index 10)> : a reference to the lexical hints hash in use when the context was created (only on perl 5.10 or greater).
431
432 =back
433
434 =head2 C<uplevel>
435
436     my @ret = uplevel { ...; return @ret };
437     my @ret = uplevel { my @args = @_; ...; return @ret } @args, $context;
438     my @ret = &uplevel($callback, @args, $context);
439
440 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.
441 The code is executed in the context of the C<uplevel> call, and what it returns is returned as-is by C<uplevel>.
442
443     sub target {
444      faker(@_);
445     }
446
447     sub faker {
448      uplevel {
449       map { 1 / $_ } @_;
450      } @_ => CALLER(1);
451     }
452
453     my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
454     my $count    = target(1, 2, 4); # $count is 3
455
456 Note that if C<@args> is empty, then the C<$context> parameter is optional and defaults to the current context ; otherwise it is mandatory.
457
458 L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
459 Both are identical, with the following caveats :
460
461 =over 4
462
463 =item *
464
465 The L<Sub::Uplevel> implementation of C<uplevel> may execute a code reference in the context of B<any> upper stack frame.
466 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.
467
468 =item *
469
470 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.
471 This means that :
472
473     eval {
474      sub {
475       local $@;
476       eval {
477        sub {
478         uplevel { die 'wut' } CALLER(2); # for Scope::Upper
479         # uplevel(3, sub { die 'wut' })  # for Sub::Uplevel
480        }->();
481       };
482       print "inner block: $@";
483       $@ and exit;
484      }->();
485     };
486     print "outer block: $@";
487
488 will print "inner block: wut..." with L<Sub::Uplevel> and "outer block: wut..." with L<Scope::Upper>.
489
490 =item *
491
492 L<Sub::Uplevel> globally overrides the Perl keyword C<caller>, while L<Scope::Upper> does not.
493
494 =back
495
496 A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
497
498     use Scope::Upper;
499
500     sub uplevel {
501      my $frame = shift;
502      my $code  = shift;
503      my $cxt   = Scope::Upper::CALLER($frame);
504      &Scope::Upper::uplevel($code => @_ => $cxt);
505     }
506
507 Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
508
509 =head2 C<uid>
510
511     my $uid = uid;
512     my $uid = uid $context;
513
514 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.
515 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.
516
517     my $uid;
518
519     {
520      $uid = uid;
521      if ($uid eq uid()) { # yes, this is the same context
522       ...
523      }
524      {
525       if ($uid eq uid()) { # no, we are one scope below
526        ...
527       }
528       if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
529        ...
530       }
531      }
532     }
533
534     # $uid is now invalid
535
536     {
537      if ($uid eq uid()) { # no, this is another block
538       ...
539      }
540     }
541
542 For example, each loop iteration gets its own UID :
543
544     my %uids;
545
546     for (1 .. 5) {
547      my $uid = uid;
548      $uids{$uid} = $_;
549     }
550
551     # %uids has 5 entries
552
553 The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to compare them.
554
555 To check whether a given UID is valid, you can use the L</validate_uid> function.
556
557 =head2 C<validate_uid>
558
559     my $is_valid = validate_uid $uid;
560
561 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).
562
563     my $uid;
564
565     {
566      $uid = uid();
567      if (validate_uid($uid)) { # yes
568       ...
569      }
570      {
571       if (validate_uid($uid)) { # yes
572        ...
573       }
574      }
575     }
576
577     if (validate_uid($uid)) { # no
578      ...
579     }
580
581 =head1 CONSTANTS
582
583 =head2 C<SU_THREADSAFE>
584
585 True iff the module could have been built when thread-safety features.
586
587 =head1 WORDS
588
589 =head2 Constants
590
591 =head3 C<TOP>
592
593     my $top_context = TOP;
594
595 Returns the context that currently represents the highest scope.
596
597 =head3 C<HERE>
598
599     my $current_context = HERE;
600
601 The context of the current scope.
602
603 =head2 Getting a context from a context
604
605 For any of those functions, C<$from> is expected to be a context.
606 When omitted, it defaults to the current context.
607
608 =head3 C<UP>
609
610     my $upper_context = UP;
611     my $upper_context = UP $from;
612
613 The context of the scope just above C<$from>.
614
615 =head3 C<SUB>
616
617     my $sub_context = SUB;
618     my $sub_context = SUB $from;
619
620 The context of the closest subroutine above C<$from>.
621 Note that C<$from> is returned if it is already a subroutine context ; hence C<SUB SUB == SUB>.
622
623 =head3 C<EVAL>
624
625     my $eval_context = EVAL;
626     my $eval_context = EVAL $from;
627
628 The context of the closest eval above C<$from>.
629 Note that C<$from> is returned if it is already an eval context ; hence C<EVAL EVAL == EVAL>.
630
631 =head2 Getting a context from a level
632
633 Here, C<$level> should denote a number of scopes above the current one.
634 When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
635
636 =head3 C<SCOPE>
637
638     my $context = SCOPE;
639     my $context = SCOPE $level;
640
641 The C<$level>-th upper context, regardless of its type.
642
643 =head3 C<CALLER>
644
645     my $context = CALLER;
646     my $context = CALLER $level;
647
648 The context of the C<$level>-th upper subroutine/eval/format.
649 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.
650
651 =head2 Examples
652
653 Where L</reap> fires depending on the C<$cxt> :
654
655     sub {
656      eval {
657       sub {
658        {
659         reap \&cleanup => $cxt;
660         ...
661        }     # $cxt = SCOPE(0) = HERE
662        ...
663       }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
664       ...
665      };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)
666      ...
667     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
668     ...
669
670 Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
671
672     sub {
673      eval {
674       sub {
675        {
676         localize '$x' => 1 => $cxt;
677         # $cxt = SCOPE(0) = HERE
678         ...
679        }
680        # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
681        ...
682       }->();
683       # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
684       ...
685      };
686      # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
687      ...
688     }->();
689     # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
690     ...
691
692 Where L</unwind>, L</yield>, L</want_at>, L</context_info> and L</uplevel> point to depending on the C<$cxt>:
693
694     sub {
695      eval {
696       sub {
697        {
698         unwind @things => $cxt;   # or yield @things => $cxt
699                                   # or uplevel { ... } $cxt
700         ...
701        }
702        ...
703       }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
704       ...
705      };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
706      ...
707     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
708     ...
709
710     # (*) Note that uplevel() will croak if you pass that scope frame,
711     #     because it cannot target eval scopes.
712
713 =head1 EXPORT
714
715 The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>,  L</unwind>, L</yield>, L</leave>, L</want_at>, L</context_info> and L</uplevel> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
716
717 The constant L</SU_THREADSAFE> is also only exported on request, individually or by the tags C<':consts'> and C<':all'>.
718
719 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'>.
720
721 =cut
722
723 use base qw<Exporter>;
724
725 our @EXPORT      = ();
726 our %EXPORT_TAGS = (
727  funcs  => [ qw<
728   reap
729   localize localize_elem localize_delete
730   unwind yield leave
731   want_at context_info
732   uplevel
733   uid validate_uid
734  > ],
735  words  => [ qw<TOP HERE UP SUB EVAL SCOPE CALLER> ],
736  consts => [ qw<SU_THREADSAFE> ],
737 );
738 our @EXPORT_OK   = map { @$_ } values %EXPORT_TAGS;
739 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
740
741 =head1 CAVEATS
742
743 Be careful that local variables are restored in the reverse order in which they were localized.
744 Consider those examples:
745
746     local $x = 0;
747     {
748      reap sub { print $x } => HERE;
749      local $x = 1;
750      ...
751     }
752     # prints '0'
753     ...
754     {
755      local $x = 1;
756      reap sub { $x = 2 } => HERE;
757      ...
758     }
759     # $x is 0
760
761 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>.
762
763 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.
764 This is an hopeless case because C<BEGIN> blocks are executed once while localizing constructs should do their job at each run.
765 However, it's possible to hook the end of the current scope compilation with L<B::Hooks::EndOfScope>.
766
767 Some rare oddities may still happen when running inside the debugger.
768 It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes.
769
770 Calling C<goto> to replace an L</uplevel>'d code frame does not work :
771
772 =over 4
773
774 =item *
775
776 for a C<perl> older than the 5.8 series ;
777
778 =item *
779
780 for a C<DEBUGGING> C<perl> run with debugging flags set (as in C<perl -D ...>) ;
781
782 =item *
783
784 when the runloop callback is replaced by another module.
785
786 =back
787
788 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.
789
790 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 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.
791 Despite this shortcoming, this XS version of L</uplevel> should still run way faster than the pure-Perl version from L<Sub::Uplevel>.
792
793 =head1 DEPENDENCIES
794
795 L<perl> 5.6.1.
796
797 A C compiler.
798 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.
799
800 L<XSLoader> (core since perl 5.6.0).
801
802 =head1 SEE ALSO
803
804 L<perlfunc/local>, L<perlsub/"Temporary Values via local()">.
805
806 L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
807
808 L<Sub::Uplevel>.
809
810 L<Continuation::Escape> is a thin wrapper around L<Scope::Upper> that gives you a continuation passing style interface to L</unwind>.
811 It's easier to use, but it requires you to have control over the scope where you want to return.
812
813 L<Scope::Escape>.
814
815 =head1 AUTHOR
816
817 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
818
819 You can contact me by mail or on C<irc.perl.org> (vincent).
820
821 =head1 BUGS
822
823 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>.
824 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
825
826 =head1 SUPPORT
827
828 You can find documentation for this module with the perldoc command.
829
830     perldoc Scope::Upper
831
832 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scope-Upper>.
833
834 =head1 ACKNOWLEDGEMENTS
835
836 Inspired by Ricardo Signes.
837
838 Thanks to Shawn M. Moore for motivation.
839
840 =head1 COPYRIGHT & LICENSE
841
842 Copyright 2008,2009,2010,2011,2012,2013 Vincent Pit, all rights reserved.
843
844 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
845
846 =cut
847
848 1; # End of Scope::Upper