Scope::Upper - Act on upper scopes.
VERSION
- Version 0.01
+ Version 0.03
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
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.
FUNCTIONS
"reap $callback, $level"
to 1.
* A string beginning with a sigil, representing the symbol to localize
- and assign to. If the sigil is '$', then $value isn't dereferenced,
- that is
+ and to assign to. If the sigil is '$', "localize" follows the same
+ syntax as "local $x = $value", i.e. $value isn't dereferenced. For
+ example,
localize '$x', \'foo' => 0;
- will set $x to a reference to the string 'foo'. Other sigils behave
- as if a glob was passed.
+ will set $x to a reference to the string 'foo'. Other sigils ('@',
+ '%', '&' and '*') require $value to be a reference of the
+ corresponding type.
- The symbol is resolved when the actual localization takes place and
- not when "localize" is called. This means that
+ When the symbol is given by a string, it is resolved when the actual
+ localization takes place and not when "localize" is called. This
+ means that
sub tag { localize '$x', $_[0] => 1; }
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.
+ "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.
+
"TOPLEVEL"
Returns the level that currently represents the highest scope.
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" and
+ "TOPLEVEL" are only exported on request, either individually or by the
+ tags ':funcs' and ':all'.
+
+CAVEATS
+ Be careful that local variables are restored in the reverse order in
+ which they were localized. Consider those examples:
+
+ local $x = 0;
+ {
+ reap sub { print $x } => 0;
+ local $x = 1;
+ ...
+ }
+ # prints '0'
+ ...
+ {
+ local $x = 1;
+ reap sub { $x = 2 } => 0;
+ ...
+ }
+ # $x is 0
+
+ The first case is "solved" by moving the "local" before the "reap", and
+ the second by using "localize" instead of "reap".
+
+ "reap", "localize" and "localize_elem" effects can't cross "BEGIN"
+ blocks, hence calling those functions in "import" is deemed to be
+ useless. This is an hopeless case because "BEGIN" blocks are executed
+ once while localizing constructs should do their job at each run.
DEPENDENCIES
XSLoader (standard since perl 5.006).
perldoc Scope::Upper
+ Tests code coverage report is available at
+ <http://www.profvince.com/perl/cover/Scope-Upper>.
+
ACKNOWLEDGEMENTS
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.