2 Scope::Upper - Act on upper scopes.
10 use Scope::Upper qw/reap localize localize_elem localize_delete :words/;
12 sub desc { shift->{desc} }
17 # First localize $x so that it gets destroyed last
18 localize '$x' => bless({ desc => $desc }, __PACKAGE__) => UP; # one scope up
22 my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
23 print $x->desc . ": done\n";
24 } => SCOPE 1; # same as UP here
26 localize_elem '%SIG', '__WARN__' => sub {
28 my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
29 CORE::warn($x->desc . ': ' . join('', @_));
30 } => UP CALLER 0; # same as UP here
32 # delete last @ARGV element
33 localize_delete '@ARGV', -1 => UP SUB HERE; # same as UP here
40 # $x is now a X object, and @ARGV has one element less
41 warn 'what'; # warns "pie: what at ..."
43 } # "pie: done" is printed
47 use Scope::Upper qw/unwind want_at :words/;
50 my @result = shift->();
52 unwind +(want_at($cx) ? @result : scalar @result) => $cx;
59 return @things; # returns to try() and then outside zap()
65 my @what = zap(); # @what contains @things
68 This module lets you defer actions *at run-time* that will take place
69 when the control flow returns into an upper scope. Currently, you can:
71 * hook an upper scope end with "reap" ;
73 * localize variables, array/hash values or deletions of elements in
74 higher contexts with respectively "localize", "localize_elem" and
77 * return values immediately to an upper level with "unwind", and know
78 which context was in use then with "want_at".
81 In all those functions, $context refers to the target scope.
83 You have to use one or a combination of "WORDS" to build the $context
84 passed to these functions. This is needed in order to ensure that the
85 module still works when your program is ran in the debugger. The only
86 thing you can assume is that it is an *absolute* indicator of the frame,
87 which means that you can safely store it at some point and use it when
88 needed, and it will still denote the original scope.
90 "reap $callback, $context"
91 Add a destructor that calls $callback (in void context) when the upper
92 scope represented by $context ends.
94 "localize $what, $value, $context"
95 A "local" delayed to the time of first return into the upper scope
96 denoted by $context. $what can be :
98 * A glob, in which case $value can either be a glob or a reference.
99 "localize" follows then the same syntax as "local *x = $value". For
100 example, if $value is a scalar reference, then the "SCALAR" slot of
101 the glob will be set to $$value - just like "local *x = \1" sets $x
104 * A string beginning with a sigil, representing the symbol to localize
105 and to assign to. If the sigil is '$', "localize" follows the same
106 syntax as "local $x = $value", i.e. $value isn't dereferenced. For
109 localize '$x', \'foo' => HERE;
111 will set $x to a reference to the string 'foo'. Other sigils ('@',
112 '%', '&' and '*') require $value to be a reference of the
115 When the symbol is given by a string, it is resolved when the actual
116 localization takes place and not when "localize" is called. This
119 sub tag { localize '$x', $_[0] => UP }
121 will localize in the caller's namespace.
123 "localize_elem $what, $key, $value, $context"
124 Similar to "localize" but for array and hash elements. If $what is a
125 glob, the slot to fill is determined from which type of reference $value
126 is ; otherwise it's inferred from the sigil. $key is either an array
127 index or a hash key, depending of which kind of variable you localize.
129 "localize_delete $what, $key, $context"
130 Similiar to "localize", but for deleting variables or array/hash
131 elements. $what can be:
133 * A glob, in which case $key is ignored and the call is equivalent to
136 * A string beginning with '@' or '%', for which the call is equivalent
137 to respectiveley "local $a[$key]; delete $a[$key]" and "local
138 $h{$key}; delete $h{$key}".
140 * A string beginning with '&', which more or less does "undef &func"
141 in the upper scope. It's actually more powerful, as &func won't even
142 "exists" anymore. $key is ignored.
144 "unwind @values, $context"
145 Returns @values *from* the context pointed by $context, i.e. from the
146 subroutine, eval or format just above $context, and immediately restart
147 the program flow at this point - thus effectively returning to (or from,
148 depending on how you see it) an upper context.
150 The upper context isn't coerced onto @values, which is hence always
151 evaluated in list context. This means that
154 my @a = ('a' .. 'z');
159 will set $num to 'z'. You can use "want_at" to handle these cases.
162 Like "wantarray", but for the subroutine/eval/format just above
165 The previous example can then be "corrected" :
168 my @a = ('a' .. 'z');
169 unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
173 will righteously set $num to 26.
177 True iff the module could have been built when thread-safety features.
182 Returns the context that currently represents the highest scope.
185 The context of the current scope.
187 Getting a context from a context
188 For any of those functions, $from is expected to be a context. When
189 omitted, it defaults to the the current context.
192 The context of the scope just above $from.
195 The context of the closest subroutine above $from. Note that $from is
196 returned if it is already a subroutine context ; hence "SUB SUB == SUB".
199 The context of the closest eval above $from. Note that $from is returned
200 if it is already an eval context ; hence "EVAL EVAL == EVAL".
202 Getting a context from a level
203 Here, $level should denote a number of scopes above the current one.
204 When omitted, it defaults to 0 and those functions return the same
208 The $level-th upper context, regardless of its type.
211 The context of the $level-th upper subroutine/eval/format. It kind of
212 corresponds to the context represented by "caller $level", but while
213 e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
214 the top scope in the current context.
217 Where "reap" fires depending on the $cxt :
223 reap \&cleanup => $cxt;
225 } # $cxt = SCOPE(0), or HERE
227 }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
229 }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
231 }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
234 Where "localize", "localize_elem" and "localize_delete" act depending on
241 localize '$x' => 1 => $cxt;
242 # $cxt = SCOPE(0), or HERE
245 # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
248 # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
251 # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
254 # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP
257 Where "unwind" and "want_at" point to depending on the $cxt:
263 unwind @things => $cxt;
267 }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
269 }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
271 }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
275 The functions "reap", "localize", "localize_elem", "localize_delete",
276 "unwind" and "want_at" are only exported on request, either individually
277 or by the tags ':funcs' and ':all'.
279 The constant "SU_THREADSAFE" is also only exported on request,
280 individually or by the tags ':consts' and ':all'.
282 Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
283 "CALLER" that are only exported on request, individually or by the tags
287 Be careful that local variables are restored in the reverse order in
288 which they were localized. Consider those examples:
292 reap sub { print $x } => HERE;
300 reap sub { $x = 2 } => HERE;
305 The first case is "solved" by moving the "local" before the "reap", and
306 the second by using "localize" instead of "reap".
308 The effects of "reap", "localize" and "localize_elem" can't cross
309 "BEGIN" blocks, hence calling those functions in "import" is deemed to
310 be useless. This is an hopeless case because "BEGIN" blocks are executed
311 once while localizing constructs should do their job at each run.
312 However, it's possible to hook the end of the current scope compilation
313 with B::Hooks::EndOfScope.
315 Some rare oddities may still happen when running inside the debugger. It
316 may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
317 context-related fixes.
320 XSLoader (standard since perl 5.006).
323 Alias, Hook::Scope, Scope::Guard, Guard.
326 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
328 You can contact me by mail or on "irc.perl.org" (vincent).
331 Please report any bugs or feature requests to "bug-scope-upper at
332 rt.cpan.org", or through the web interface at
333 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
334 notified, and then you'll automatically be notified of progress on your
335 bug as I make changes.
338 You can find documentation for this module with the perldoc command.
342 Tests code coverage report is available at
343 <http://www.profvince.com/perl/cover/Scope-Upper>.
346 Inspired by Ricardo Signes.
348 Thanks to Shawn M. Moore for motivation.
351 Copyright 2008-2009 Vincent Pit, all rights reserved.
353 This program is free software; you can redistribute it and/or modify it
354 under the same terms as Perl itself.