]> git.vpit.fr Git - perl/modules/Scope-Upper.git/blob - lib/Scope/Upper.pm
Rename sud->new_uid_storage to sud->tmp_uid_storage
[perl/modules/Scope-Upper.git] / 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.18
13
14 =cut
15
16 our $VERSION;
17 BEGIN {
18  $VERSION = '0.18';
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 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 $callback, $context>
201
202 Adds a destructor that calls C<$callback> (in void context) when the upper scope represented by C<$context> ends.
203
204 =head2 C<localize $what, $value, $context>
205
206 Introduces a C<local> delayed to the time of first return into the upper scope denoted by C<$context>.
207 C<$what> can be :
208
209 =over 4
210
211 =item *
212
213 A glob, in which case C<$value> can either be a glob or a reference.
214 L</localize> follows then the same syntax as C<local *x = $value>.
215 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>.
216
217 =item *
218
219 A string beginning with a sigil, representing the symbol to localize and to assign to.
220 If the sigil is C<'$'>, L</localize> follows the same syntax as C<local $x = $value>, i.e. C<$value> isn't dereferenced.
221 For example,
222
223     localize '$x', \'foo' => HERE;
224
225 will set C<$x> to a reference to the string C<'foo'>.
226 Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type.
227
228 When the symbol is given by a string, it is resolved when the actual localization takes place and not when L</localize> is called.
229 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.
230 For example,
231
232     {
233      package Scope;
234      sub new { localize '$tag', $_[0] => UP }
235     }
236
237     {
238      package Tool;
239      {
240       Scope->new;
241       ...
242      }
243     }
244
245 will localize C<$Tool::tag> and not C<$Scope::tag>.
246 If you want the other behaviour, you just have to specify C<$what> as a glob or a qualified name.
247
248 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.
249 This situation never arises with C<local> because it only compiles when the localized variable is already declared.
250 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.
251
252 =back
253
254 =head2 C<localize_elem $what, $key, $value, $context>
255
256 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>.
257 Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
258 The two only valid types are array and hash ; for anything besides those, L</localize_elem> will throw an exception.
259 C<$key> is either an array index or a hash key, depending of which kind of variable you localize.
260
261 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.
262
263 =head2 C<localize_delete $what, $key, $context>
264
265 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>.
266 C<$what> can be:
267
268 =over 4
269
270 =item *
271
272 A glob, in which case C<$key> is ignored and the call is equivalent to C<local *x>.
273
274 =item *
275
276 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}>.
277
278 =item *
279
280 A string beginning with C<'&'>, which more or less does C<undef &func> in the upper scope.
281 It's actually more powerful, as C<&func> won't even C<exists> anymore.
282 C<$key> is ignored.
283
284 =back
285
286 =head2 C<unwind @values, $context>
287
288 Returns C<@values> I<from> the context pointed by C<$context>, i.e. from the subroutine, eval or format at or just above C<$context>, and immediately restart the program flow at this point - thus effectively returning to an upper scope.
289
290 The upper context isn't coerced onto C<@values>, which is hence always evaluated in list context.
291 This means that
292
293     my $num = sub {
294      my @a = ('a' .. 'z');
295      unwind @a => HERE;
296      # not reached
297     }->();
298
299 will set C<$num> to C<'z'>.
300 You can use L</want_at> to handle these cases.
301
302 =head2 C<want_at $context>
303
304 Like C<wantarray>, but for the subroutine/eval/format at or just above C<$context>.
305
306 The previous example can then be "corrected" :
307
308     my $num = sub {
309      my @a = ('a' .. 'z');
310      unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
311      # not reached
312     }->();
313
314 will rightfully set C<$num> to C<26>.
315
316 =head2 C<uplevel $code, @args, $context>
317
318 Executes the code reference C<$code> 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.
319 The code is executed in the context of the C<uplevel> call, and what it returns is returned as-is by C<uplevel>.
320
321     sub target {
322      faker(@_);
323     }
324
325     sub faker {
326      uplevel {
327       map { 1 / $_ } @_;
328      } @_ => CALLER(1);
329     }
330
331     my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
332     my $count    = target(1, 2, 4); # $count is 3
333
334 L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
335 Both are identical, with the following caveats :
336
337 =over 4
338
339 =item *
340
341 The L<Sub::Uplevel> implementation of C<uplevel> may execute a code reference in the context of B<any> upper stack frame.
342 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.
343
344 =item *
345
346 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.
347 This means that :
348
349     eval {
350      sub {
351       local $@;
352       eval {
353        sub {
354         uplevel { die 'wut' } CALLER(2); # for Scope::Upper
355         # uplevel(3, sub { die 'wut' })  # for Sub::Uplevel
356        }->();
357       };
358       print "inner block: $@";
359       $@ and exit;
360      }->();
361     };
362     print "outer block: $@";
363
364 will print "inner block: wut..." with L<Sub::Uplevel> and "outer block: wut..." with L<Scope::Upper>.
365
366 =item *
367
368 L<Sub::Uplevel> globally overrides the Perl keyword C<caller>, while L<Scope::Upper> does not.
369
370 =back
371
372 A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
373
374     use Scope::Upper;
375
376     sub uplevel {
377      my $frame = shift;
378      my $code  = shift;
379      my $cxt   = Scope::Upper::CALLER($frame);
380      &Scope::Upper::uplevel($code => @_ => $cxt);
381     }
382
383 Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
384
385 =head2 C<uid $context>
386
387 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.
388 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.
389
390     my $uid;
391
392     {
393      $uid = uid;
394      if ($uid eq uid()) { # yes, this is the same context
395       ...
396      }
397      {
398       if ($uid eq uid()) { # no, we are one scope below
399        ...
400       }
401       if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
402        ...
403       }
404      }
405     }
406
407     # $uid is now invalid
408
409     {
410      if ($uid eq uid()) { # no, this is another block
411       ...
412      }
413     }
414
415 For example, each loop iteration gets its own UID :
416
417     my %uids;
418
419     for (1 .. 5) {
420      my $uid = uid;
421      $uids{$uid} = $_;
422     }
423
424     # %uids has 5 entries
425
426 The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to compare them.
427
428 To check whether a given UID is valid, you can use the L</validate_uid> function.
429
430 =head2 C<validate_uid $uid>
431
432 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).
433
434     my $uid;
435
436     {
437      $uid = uid();
438      if (validate_uid($uid)) { # yes
439       ...
440      }
441      {
442       if (validate_uid($uid)) { # yes
443        ...
444       }
445      }
446     }
447
448     if (validate_uid($uid)) { # no
449      ...
450     }
451
452 =head1 CONSTANTS
453
454 =head2 C<SU_THREADSAFE>
455
456 True iff the module could have been built when thread-safety features.
457
458 =head1 WORDS
459
460 =head2 Constants
461
462 =head3 C<TOP>
463
464 Returns the context that currently represents the highest scope.
465
466 =head3 C<HERE>
467
468 The context of the current scope.
469
470 =head2 Getting a context from a context
471
472 For any of those functions, C<$from> is expected to be a context.
473 When omitted, it defaults to the the current context.
474
475 =head3 C<UP $from>
476
477 The context of the scope just above C<$from>.
478
479 =head3 C<SUB $from>
480
481 The context of the closest subroutine above C<$from>.
482 Note that C<$from> is returned if it is already a subroutine context ; hence C<SUB SUB == SUB>.
483
484 =head3 C<EVAL $from>
485
486 The context of the closest eval above C<$from>.
487 Note that C<$from> is returned if it is already an eval context ; hence C<EVAL EVAL == EVAL>.
488
489 =head2 Getting a context from a level
490
491 Here, C<$level> should denote a number of scopes above the current one.
492 When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
493
494 =head3 C<SCOPE $level>
495
496 The C<$level>-th upper context, regardless of its type.
497
498 =head3 C<CALLER $level>
499
500 The context of the C<$level>-th upper subroutine/eval/format.
501 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.
502
503 =head2 Examples
504
505 Where L</reap> fires depending on the C<$cxt> :
506
507     sub {
508      eval {
509       sub {
510        {
511         reap \&cleanup => $cxt;
512         ...
513        }     # $cxt = SCOPE(0) = HERE
514        ...
515       }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
516       ...
517      };      # $cxt = SCOPE(2) = UP UP =  UP SUB = EVAL = CALLER(1)
518      ...
519     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
520     ...
521
522 Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
523
524     sub {
525      eval {
526       sub {
527        {
528         localize '$x' => 1 => $cxt;
529         # $cxt = SCOPE(0) = HERE
530         ...
531        }
532        # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
533        ...
534       }->();
535       # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
536       ...
537      };
538      # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
539      ...
540     }->();
541     # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
542     ...
543
544 Where L</unwind>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
545
546     sub {
547      eval {
548       sub {
549        {
550         unwind @things => $cxt;   # or uplevel { ... } $cxt;
551         ...
552        }
553        ...
554       }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
555       ...
556      };      # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
557      ...
558     }->();   # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
559     ...
560
561     # (*) Note that uplevel() will croak if you pass that scope frame,
562     #     because it cannot target eval scopes.
563
564 =head1 EXPORT
565
566 The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>,  L</unwind>, L</want_at> and L</uplevel> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
567
568 The constant L</SU_THREADSAFE> is also only exported on request, individually or by the tags C<':consts'> and C<':all'>.
569
570 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'>.
571
572 =cut
573
574 use base qw<Exporter>;
575
576 our @EXPORT      = ();
577 our %EXPORT_TAGS = (
578  funcs  => [ qw<
579   reap
580   localize localize_elem localize_delete
581   unwind want_at
582   uplevel
583   uid validate_uid
584  > ],
585  words  => [ qw<TOP HERE UP SUB EVAL SCOPE CALLER> ],
586  consts => [ qw<SU_THREADSAFE> ],
587 );
588 our @EXPORT_OK   = map { @$_ } values %EXPORT_TAGS;
589 $EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
590
591 =head1 CAVEATS
592
593 Be careful that local variables are restored in the reverse order in which they were localized.
594 Consider those examples:
595
596     local $x = 0;
597     {
598      reap sub { print $x } => HERE;
599      local $x = 1;
600      ...
601     }
602     # prints '0'
603     ...
604     {
605      local $x = 1;
606      reap sub { $x = 2 } => HERE;
607      ...
608     }
609     # $x is 0
610
611 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>.
612
613 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.
614 This is an hopeless case because C<BEGIN> blocks are executed once while localizing constructs should do their job at each run.
615 However, it's possible to hook the end of the current scope compilation with L<B::Hooks::EndOfScope>.
616
617 Some rare oddities may still happen when running inside the debugger.
618 It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes.
619
620 Calling C<goto> to replace an L</uplevel>'d code frame does not work :
621
622 =over 4
623
624 =item *
625
626 for a C<perl> older than the 5.8 series ;
627
628 =item *
629
630 for a C<DEBUGGING> C<perl> run with debugging flags set (as in C<perl -D ...>) ;
631
632 =item *
633
634 when the runloop callback is replaced by another module.
635
636 =back
637
638 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.
639
640 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.
641 Despite this shortcoming, this XS version of L</uplevel> should still run way faster than the pure-Perl version from L<Sub::Uplevel>.
642
643 =head1 DEPENDENCIES
644
645 L<XSLoader> (standard since perl 5.006).
646
647 =head1 SEE ALSO
648
649 L<perlfunc/local>, L<perlsub/"Temporary Values via local()">.
650
651 L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
652
653 L<Sub::Uplevel>.
654
655 L<Continuation::Escape> is a thin wrapper around L<Scope::Upper> that gives you a continuation passing style interface to L</unwind>.
656 It's easier to use, but it requires you to have control over the scope where you want to return.
657
658 L<Scope::Escape>.
659
660 =head1 AUTHOR
661
662 Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
663
664 You can contact me by mail or on C<irc.perl.org> (vincent).
665
666 =head1 BUGS
667
668 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>.
669 I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
670
671 =head1 SUPPORT
672
673 You can find documentation for this module with the perldoc command.
674
675     perldoc Scope::Upper
676
677 Tests code coverage report is available at L<http://www.profvince.com/perl/cover/Scope-Upper>.
678
679 =head1 ACKNOWLEDGEMENTS
680
681 Inspired by Ricardo Signes.
682
683 Thanks to Shawn M. Moore for motivation.
684
685 =head1 COPYRIGHT & LICENSE
686
687 Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
688
689 This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
690
691 =cut
692
693 1; # End of Scope::Upper