Scope::Upper - Act on upper scopes.
VERSION
- Version 0.01
+ Version 0.04
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.
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.
- "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.
+
+ "want_at $level"
+ Like "wantarray", but for the subroutine/eval/format context just above
+ $level.
+
+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 corresponding to the stack referenced by "caller $stack".
+
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
+ 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.
projects / perl / modules / Scope-Upper.git / blobdiff