Scope::Upper - Act on upper scopes.
VERSION
- Version 0.02
+ Version 0.05
SYNOPSIS
package X;
- use Scope::Upper qw/reap localize localize_elem/;
+ use Scope::Upper qw/reap localize localize_elem localize_delete/;
sub desc { shift->{desc} }
my $x = do { no strict 'refs'; ${$pkg.'::x'} }; # Get the $x in the scope
CORE::warn($x->desc . ': ' . join('', @_));
} => 1;
+
+ localize_delete '@ARGV', $#ARGV => 1; # delete last @ARGV element
}
package Y;
{
X::set_tag('pie');
- # $x is now a X object
+ # $x is now a X object, and @ARGV has one element less
warn 'what'; # warns "pie: what at ..."
...
} # "pie: done" is printed
+ package Z;
+
+ use Scope::Upper qw/unwind want_at :words/;
+
+ sub try (&) {
+ my @result = shift->();
+ my $cx = SUB UP SUB;
+ unwind +(want_at($cx) ? @result : scalar @result) => $cx;
+ }
+
+ ...
+
+ sub zap {
+ try {
+ return @things; # returns to try() and then outside zap()
+ }
+ }
+
+ my @what = zap(); # @what contains @things
+
DESCRIPTION
This module lets you defer actions that will take place when the control
flow returns into an upper scope. Currently, you can hook an upper scope
- end, or localize variables and array/hash values in higher contexts.
+ end, or localize variables, array/hash values or deletions of elements
+ in higher contexts. You can also return to an upper level and know which
+ context was in use then.
FUNCTIONS
"reap $callback, $level"
is ; otherwise it's inferred from the sigil. $key is either an array
index or a hash key, depending of which kind of variable you localize.
- "TOPLEVEL"
+ "localize_delete $what, $key, $level"
+ Similiar to "localize", but for deleting variables or array/hash
+ elements. $what can be:
+
+ * A glob, in which case $key is ignored and the call is equivalent to
+ "local *x".
+
+ * A string beginning with '@' or '%', for which the call is equivalent
+ to respectiveley "local $a[$key]; delete $a[$key]" and "local
+ $h{$key}; delete $h{$key}".
+
+ * A string beginning with '&', which more or less does "undef &func"
+ in the upper scope. It's actually more powerful, as &func won't even
+ "exists" anymore. $key is ignored.
+
+ "unwind @values, $level"
+ Returns @values *from* the context indicated by $level, i.e. from the
+ subroutine, eval or format just above $level.
+
+ The upper level isn't coerced onto @values, which is hence always
+ evaluated in list context. This means that
+
+ my $num = sub {
+ my @a = ('a' .. 'z');
+ unwind @a => 0;
+ }->();
+
+ will set $num to 'z'. You can use "want_at" to handle these cases.
+
+ "want_at $level"
+ Like "wantarray", but for the subroutine/eval/format context just above
+ $level.
+
+ The previous example can then be "corrected" :
+
+ my $num = sub {
+ my @a = ('a' .. 'z');
+ unwind +(want_at(0) ? @a : scalar @a) => 0;
+ }->();
+
+ will righteously set $num to 26.
+
+WORDS
+ "TOP"
Returns the level that currently represents the highest scope.
+ "HERE"
+ The current level - i.e. 0.
+
+ "UP $from"
+ The level of the scope just above $from.
+
+ "DOWN $from"
+ The level of the scope just below $from.
+
+ "SUB $from"
+ The level of the closest subroutine context above $from.
+
+ "EVAL $from"
+ The level of the closest eval context above $from.
+
+ If $from is omitted in any of those functions, the current level is used
+ as the reference level.
+
+ "CALLER $stack"
+ The level of the $stack-th upper subroutine/eval/format context. It kind
+ of corresponds to the context represented by "caller $stack", but while
+ e.g. "caller 0" refers to the caller context, "CALLER 0" will refer to
+ the top scope in the current context. For example,
+
+ reap ... => CALLER(0)
+
+ will fire the destructor when the current subroutine/eval/format ends.
+
EXPORT
- The functions "reap", "localize", "localize_elem" and "TOPLEVEL" are
- only exported on request, either individually or by the tags ':funcs'
- and ':all'.
+ The functions "reap", "localize", "localize_elem", "localize_delete",
+ "unwind" and "want_at" are only exported on request, either individually
+ or by the tags ':funcs' and ':all'.
+
+ Same goes for the words "TOP", "HERE", "UP", "DOWN", "SUB", "EVAL" and
+ "CALLER" that are only exported on request, individually or by the tags
+ ':words' and ':all'.
CAVEATS
Be careful that local variables are restored in the reverse order in
Inspired by Ricardo Signes.
COPYRIGHT & LICENSE
- Copyright 2008 Vincent Pit, all rights reserved.
+ Copyright 2008-2009 Vincent Pit, all rights reserved.
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.