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.
178 Returns the context that currently represents the highest scope.
181 The context of the current scope.
183 Getting a context from a context
184 For any of those functions, $from is expected to be a context. When
185 omitted, it defaults to the the current context.
188 The context of the scope just above $from.
191 The context of the closest subroutine above $from. Note that $from is
192 returned if it is already a subroutine context ; hence "SUB SUB == SUB".
195 The context of the closest eval above $from. Note that $from is returned
196 if it is already an eval context ; hence "EVAL EVAL == EVAL".
198 Getting a context from a level
199 Here, $level should denote a number of scopes above the current one.
200 When omitted, it defaults to 0 and those functions return the same
204 The $level-th upper context, regardless of its type.
207 The context of the $level-th upper subroutine/eval/format. It kind of
208 corresponds to the context represented by "caller $level", but while
209 e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
210 the top scope in the current context.
213 Where "reap" fires depending on the $cxt :
219 reap \&cleanup => $cxt;
221 } # $cxt = SCOPE(0), or HERE
223 }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
225 }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
227 }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
230 Where "localize", "localize_elem" and "localize_delete" act depending on
237 localize '$x' => 1 => $cxt;
238 # $cxt = SCOPE(0), or HERE
241 # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
244 # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
247 # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
250 # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP
253 Where "unwind" and "want_at" point to depending on the $cxt:
259 unwind @things => $cxt;
263 }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
265 }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
267 }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
271 The functions "reap", "localize", "localize_elem", "localize_delete",
272 "unwind" and "want_at" are only exported on request, either individually
273 or by the tags ':funcs' and ':all'.
275 Same goes for the words "TOP", "HERE", "UP", "SUB", "EVAL", "SCOPE" and
276 "CALLER" that are only exported on request, individually or by the tags
280 Be careful that local variables are restored in the reverse order in
281 which they were localized. Consider those examples:
285 reap sub { print $x } => HERE;
293 reap sub { $x = 2 } => HERE;
298 The first case is "solved" by moving the "local" before the "reap", and
299 the second by using "localize" instead of "reap".
301 The effects of "reap", "localize" and "localize_elem" can't cross
302 "BEGIN" blocks, hence calling those functions in "import" is deemed to
303 be useless. This is an hopeless case because "BEGIN" blocks are executed
304 once while localizing constructs should do their job at each run.
305 However, it's possible to hook the end of the current scope compilation
306 with B::Hooks::EndOfScope.
308 Some rare oddities may still happen when running inside the debugger. It
309 may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some
310 context-related fixes.
313 XSLoader (standard since perl 5.006).
316 Alias, Hook::Scope, Scope::Guard, Guard.
319 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
321 You can contact me by mail or on "irc.perl.org" (vincent).
324 Please report any bugs or feature requests to "bug-scope-upper at
325 rt.cpan.org", or through the web interface at
326 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
327 notified, and then you'll automatically be notified of progress on your
328 bug as I make changes.
331 You can find documentation for this module with the perldoc command.
335 Tests code coverage report is available at
336 <http://www.profvince.com/perl/cover/Scope-Upper>.
339 Inspired by Ricardo Signes.
341 Thanks to Shawn M. Moore for motivation.
344 Copyright 2008-2009 Vincent Pit, all rights reserved.
346 This program is free software; you can redistribute it and/or modify it
347 under the same terms as Perl itself.