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