2 Scope::Upper - Act on upper scopes.
10 use Scope::Upper qw/reap localize localize_elem localize_delete/;
12 sub desc { shift->{desc} }
17 # First localize $x so that it gets destroyed last
18 localize '$x' => bless({ desc => $desc }, __PACKAGE__) => 1;
22 my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
23 print $x->desc . ": done\n";
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('', @_));
32 localize_delete '@ARGV', $#ARGV => 1; # delete last @ARGV element
39 # $x is now a X object, and @ARGV has one element less
40 warn 'what'; # warns "pie: what at ..."
42 } # "pie: done" is printed
46 use Scope::Upper qw/unwind want_at :words/;
49 my @result = shift->();
51 unwind +(want_at($cx) ? @result : scalar @result) => $cx;
58 return @things; # returns to try() and then outside zap()
62 my @what = zap(); # @what contains @things
65 This module lets you defer actions that will take place when the control
66 flow returns into an upper scope. Currently, you can hook an upper scope
67 end, or localize variables, array/hash values or deletions of elements
68 in higher contexts. You can also return to an upper level and know which
69 context was in use then.
72 "reap $callback, $level"
73 Add a destructor that calls $callback when the $level-th upper scope
74 ends, where 0 corresponds to the current scope.
76 "localize $what, $value, $level"
77 A "local" delayed to the time of first return into the $level-th upper
80 * A glob, in which case $value can either be a glob or a reference.
81 "localize" follows then the same syntax as "local *x = $value". For
82 example, if $value is a scalar reference, then the "SCALAR" slot of
83 the glob will be set to $$value - just like "local *x = \1" sets $x
86 * A string beginning with a sigil, representing the symbol to localize
87 and to assign to. If the sigil is '$', "localize" follows the same
88 syntax as "local $x = $value", i.e. $value isn't dereferenced. For
91 localize '$x', \'foo' => 0;
93 will set $x to a reference to the string 'foo'. Other sigils ('@',
94 '%', '&' and '*') require $value to be a reference of the
97 When the symbol is given by a string, it is resolved when the actual
98 localization takes place and not when "localize" is called. This
101 sub tag { localize '$x', $_[0] => 1; }
103 will localize in the caller's namespace.
105 "localize_elem $what, $key, $value, $level"
106 Similar to "localize" but for array and hash elements. If $what is a
107 glob, the slot to fill is determined from which type of reference $value
108 is ; otherwise it's inferred from the sigil. $key is either an array
109 index or a hash key, depending of which kind of variable you localize.
111 "localize_delete $what, $key, $level"
112 Similiar to "localize", but for deleting variables or array/hash
113 elements. $what can be:
115 * A glob, in which case $key is ignored and the call is equivalent to
118 * A string beginning with '@' or '%', for which the call is equivalent
119 to respectiveley "local $a[$key]; delete $a[$key]" and "local
120 $h{$key}; delete $h{$key}".
122 * A string beginning with '&', which more or less does "undef &func"
123 in the upper scope. It's actually more powerful, as &func won't even
124 "exists" anymore. $key is ignored.
126 "unwind @values, $level"
127 Returns @values *from* the context indicated by $level, i.e. from the
128 subroutine, eval or format just above $level.
130 The upper level isn't coerced onto @values, which is hence always
131 evaluated in list context. This means that
134 my @a = ('a' .. 'z');
138 will set $num to 'z'. You can use "want_at" to handle these cases.
141 Like "wantarray", but for the subroutine/eval/format context just above
144 The previous example can then be "corrected" :
147 my @a = ('a' .. 'z');
148 unwind +(want_at(0) ? @a : scalar @a) => 0;
151 will righteously set $num to 26.
155 Returns the level that currently represents the highest scope.
158 The current level - i.e. 0.
161 The level of the scope just above $from.
164 The level of the scope just below $from.
167 The level of the closest subroutine context above $from.
170 The level of the closest eval context above $from.
172 If $from is omitted in any of those functions, the current level is used
173 as the reference level.
176 The level of the $stack-th upper subroutine/eval/format context. It kind
177 of corresponds to the context represented by "caller $stack", but while
178 e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
179 the top scope in the current context. For example,
181 reap ... => CALLER(0)
183 will fire the destructor when the current subroutine/eval/format ends.
186 The functions "reap", "localize", "localize_elem", "localize_delete",
187 "unwind" and "want_at" are only exported on request, either individually
188 or by the tags ':funcs' and ':all'.
190 Same goes for the words "TOP", "HERE", "UP", "DOWN", "SUB", "EVAL" and
191 "CALLER" that are only exported on request, individually or by the tags
195 Be careful that local variables are restored in the reverse order in
196 which they were localized. Consider those examples:
200 reap sub { print $x } => 0;
208 reap sub { $x = 2 } => 0;
213 The first case is "solved" by moving the "local" before the "reap", and
214 the second by using "localize" instead of "reap".
216 "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
217 blocks, hence calling those functions in "import" is deemed to be
218 useless. This is an hopeless case because "BEGIN" blocks are executed
219 once while localizing constructs should do their job at each run.
222 XSLoader (standard since perl 5.006).
225 Alias, Hook::Scope, Scope::Guard, Guard.
228 Vincent Pit, "<perl at profvince.com>", <http://www.profvince.com>.
230 You can contact me by mail or on "irc.perl.org" (vincent).
233 Please report any bugs or feature requests to "bug-scope-upper at
234 rt.cpan.org", or through the web interface at
235 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Scope-Upper>. I will be
236 notified, and then you'll automatically be notified of progress on your
237 bug as I make changes.
240 You can find documentation for this module with the perldoc command.
244 Tests code coverage report is available at
245 <http://www.profvince.com/perl/cover/Scope-Upper>.
248 Inspired by Ricardo Signes.
251 Copyright 2008-2009 Vincent Pit, all rights reserved.
253 This program is free software; you can redistribute it and/or modify it
254 under the same terms as Perl itself.