=head1 VERSION
-Version 0.10
+Version 0.18
=cut
our $VERSION;
BEGIN {
- $VERSION = '0.10';
+ $VERSION = '0.18';
}
=head1 SYNOPSIS
package Scope;
- use Scope::Upper qw/reap localize localize_elem localize_delete :words/;
+ use Scope::Upper qw<
+ reap localize localize_elem localize_delete
+ :words
+ >;
sub new {
my ($class, $name) = @_;
package UserLand;
{
- Scope->new("top"); # initializes $UserLand::tag
+ Scope->new("top"); # initializes $UserLand::tag
{
Scope->catch;
- my $one = 1 + undef; # prints "top: Use of uninitialized value..."
+ my $one = 1 + undef; # prints "top: Use of uninitialized value..."
{
Scope->private;
eval { require Cwd };
- print $@; # prints "Can't locate Cwd.pm in @INC (@INC contains:) at..."
- }
+ print $@; # prints "Can't locate Cwd.pm in @INC
+ } # (@INC contains:) at..."
- require Cwd; # loads Cwd.pm
+ require Cwd; # loads Cwd.pm
}
- } # prints "top: done"
+ } # prints "top: done"
L</unwind> and L</want_at> :
package Try;
- use Scope::Upper qw/unwind want_at :words/;
+ use Scope::Upper qw<unwind want_at :words>;
sub try (&) {
my @result = shift->();
sub zap {
try {
- my @things = qw/a b c/;
+ my @things = qw<a b c>;
return @things; # returns to try() and then outside zap()
# not reached
};
# not reached
}
- my @stuff = zap(); # @stuff contains qw/a b c/
+ my @stuff = zap(); # @stuff contains qw<a b c>
my $stuff = zap(); # $stuff contains 3
+L</uplevel> :
+
+ package Uplevel;
+
+ use Scope::Upper qw<uplevel CALLER>;
+
+ sub target {
+ faker(@_);
+ }
+
+ sub faker {
+ uplevel {
+ my $sub = (caller 0)[3];
+ print "$_[0] from $sub()";
+ } @_ => CALLER(1);
+ }
+
+ target('hello'); # "hello from Uplevel::target()"
+
+L</uid> and L</validate_uid> :
+
+ use Scope::Upper qw<uid validate_uid>;
+
+ my $uid;
+
+ {
+ $uid = uid();
+ {
+ if ($uid eq uid(UP)) { # yes
+ ...
+ }
+ if (validate_uid($uid)) { # yes
+ ...
+ }
+ }
+ }
+
+ if (validate_uid($uid)) { # no
+ ...
+ }
+
=head1 DESCRIPTION
This module lets you defer actions I<at run-time> that will take place when the control flow returns into an upper scope.
=item *
-return values immediately to an upper level with L</unwind>, and know which context was in use then with L</want_at>.
+return values immediately to an upper level with L</unwind>, and know which context was in use then with L</want_at> ;
+
+=item *
+
+execute a subroutine in the setting of an upper subroutine stack frame with L</uplevel> ;
+
+=item *
+
+uniquely identify contextes with L</uid> and L</validate_uid>.
=back
will set C<$x> to a reference to the string C<'foo'>.
Other sigils (C<'@'>, C<'%'>, C<'&'> and C<'*'>) require C<$value> to be a reference of the corresponding type.
-When the symbol is given by a string, it is resolved when the actual localization takes place and not when C<localize> is called.
-Thus, if the symbol name is not qualified, it will refer to the variable in the package where the localization actually takes place and not in the one where the C<localize> call was compiled.
+When the symbol is given by a string, it is resolved when the actual localization takes place and not when L</localize> is called.
+Thus, if the symbol name is not qualified, it will refer to the variable in the package where the localization actually takes place and not in the one where the L</localize> call was compiled.
For example,
{
=head2 C<localize_elem $what, $key, $value, $context>
Introduces a C<local $what[$key] = $value> or C<local $what{$key} = $value> delayed to the time of first return into the upper scope denoted by C<$context>.
-Just like for L</localize>, the type of localization is determined from which kind of reference C<$value> is when C<$what> is a glob, and from the sigil when it's a string.
+Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
+The two only valid types are array and hash ; for anything besides those, L</localize_elem> will throw an exception.
C<$key> is either an array index or a hash key, depending of which kind of variable you localize.
If C<$what> is a string pointing to an undeclared variable, the variable will be vivified as soon as the localization occurs and emptied when it ends, although it will still exist in its glob.
will rightfully set C<$num> to C<26>.
+=head2 C<uplevel $code, @args, $context>
+
+Executes the code reference C<$code> with arguments C<@args> as if it were located at the subroutine stack frame pointed by C<$context>, effectively fooling C<caller> and C<die> into believing that the call actually happened higher in the stack.
+The code is executed in the context of the C<uplevel> call, and what it returns is returned as-is by C<uplevel>.
+
+ sub target {
+ faker(@_);
+ }
+
+ sub faker {
+ uplevel {
+ map { 1 / $_ } @_;
+ } @_ => CALLER(1);
+ }
+
+ my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
+ my $count = target(1, 2, 4); # $count is 3
+
+L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
+Both are identical, with the following caveats :
+
+=over 4
+
+=item *
+
+The L<Sub::Uplevel> implementation of C<uplevel> may execute a code reference in the context of B<any> upper stack frame.
+The L<Scope::Upper> version can only uplevel to a B<subroutine> stack frame, and will croak if you try to target an C<eval> or a format.
+
+=item *
+
+Exceptions thrown from the code called by this version of C<uplevel> will not be caught by C<eval> blocks between the target frame and the uplevel call, while they will for L<Sub::Uplevel>'s version.
+This means that :
+
+ eval {
+ sub {
+ local $@;
+ eval {
+ sub {
+ uplevel { die 'wut' } CALLER(2); # for Scope::Upper
+ # uplevel(3, sub { die 'wut' }) # for Sub::Uplevel
+ }->();
+ };
+ print "inner block: $@";
+ $@ and exit;
+ }->();
+ };
+ print "outer block: $@";
+
+will print "inner block: wut..." with L<Sub::Uplevel> and "outer block: wut..." with L<Scope::Upper>.
+
+=item *
+
+L<Sub::Uplevel> globally overrides the Perl keyword C<caller>, while L<Scope::Upper> does not.
+
+=back
+
+A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
+
+ use Scope::Upper;
+
+ sub uplevel {
+ my $frame = shift;
+ my $code = shift;
+ my $cxt = Scope::Upper::CALLER($frame);
+ &Scope::Upper::uplevel($code => @_ => $cxt);
+ }
+
+Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
+
+=head2 C<uid $context>
+
+Returns an unique identifier (UID) for the context (or dynamic scope) pointed by C<$context>, or for the current context if C<$context> is omitted.
+This UID will only be valid for the life time of the context it represents, and another UID will be generated next time the same scope is executed.
+
+ my $uid;
+
+ {
+ $uid = uid;
+ if ($uid eq uid()) { # yes, this is the same context
+ ...
+ }
+ {
+ if ($uid eq uid()) { # no, we are one scope below
+ ...
+ }
+ if ($uid eq uid(UP)) { # yes, UP points to the same scope as $uid
+ ...
+ }
+ }
+ }
+
+ # $uid is now invalid
+
+ {
+ if ($uid eq uid()) { # no, this is another block
+ ...
+ }
+ }
+
+For example, each loop iteration gets its own UID :
+
+ my %uids;
+
+ for (1 .. 5) {
+ my $uid = uid;
+ $uids{$uid} = $_;
+ }
+
+ # %uids has 5 entries
+
+The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to compare them.
+
+To check whether a given UID is valid, you can use the L</validate_uid> function.
+
+=head2 C<validate_uid $uid>
+
+Returns true if and only if C<$uid> is the UID of a currently valid context (that is, it designates a scope that is higher than the current one in the call stack).
+
+ my $uid;
+
+ {
+ $uid = uid();
+ if (validate_uid($uid)) { # yes
+ ...
+ }
+ {
+ if (validate_uid($uid)) { # yes
+ ...
+ }
+ }
+ }
+
+ if (validate_uid($uid)) { # no
+ ...
+ }
+
=head1 CONSTANTS
=head2 C<SU_THREADSAFE>
{
reap \&cleanup => $cxt;
...
- } # $cxt = SCOPE(0), or HERE
+ } # $cxt = SCOPE(0) = HERE
...
- }->(); # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+ }->(); # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
...
- }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+ }; # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
...
- }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+ }->(); # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
...
Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
sub {
{
localize '$x' => 1 => $cxt;
- # $cxt = SCOPE(0), or HERE
+ # $cxt = SCOPE(0) = HERE
...
}
- # $cxt = SCOPE(1), or UP, or SUB, or CALLER, or CALLER(0)
+ # $cxt = SCOPE(1) = UP = SUB = CALLER(0)
...
}->();
- # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+ # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1)
...
};
- # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+ # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
...
}->();
- # $cxt = SCOPE(4), UP SUB UP SUB, or UP SUB EVAL, or UP CALLER(2), or TOP
+ # $cxt = SCOPE(4), UP SUB UP SUB = UP SUB EVAL = UP CALLER(2) = TOP
...
-Where L</unwind> and L</want_at> point to depending on the C<$cxt>:
+Where L</unwind>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
sub {
eval {
sub {
{
- unwind @things => $cxt;
+ unwind @things => $cxt; # or uplevel { ... } $cxt;
...
}
...
- }->(); # $cxt = SCOPE(0 .. 1), or HERE, or UP, or SUB, or CALLER(0)
+ }->(); # $cxt = SCOPE(0) = SCOPE(1) = HERE = UP = SUB = CALLER(0)
...
- }; # $cxt = SCOPE(2), or UP UP, or UP SUB, or EVAL, or CALLER(1)
+ }; # $cxt = SCOPE(2) = UP UP = UP SUB = EVAL = CALLER(1) (*)
...
- }->(); # $cxt = SCOPE(3), or SUB UP SUB, or SUB EVAL, or CALLER(2)
+ }->(); # $cxt = SCOPE(3) = SUB UP SUB = SUB EVAL = CALLER(2)
...
+ # (*) Note that uplevel() will croak if you pass that scope frame,
+ # because it cannot target eval scopes.
+
=head1 EXPORT
-The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>, L</unwind> and L</want_at> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
+The functions L</reap>, L</localize>, L</localize_elem>, L</localize_delete>, L</unwind>, L</want_at> and L</uplevel> are only exported on request, either individually or by the tags C<':funcs'> and C<':all'>.
The constant L</SU_THREADSAFE> is also only exported on request, individually or by the tags C<':consts'> and C<':all'>.
=cut
-use base qw/Exporter/;
+use base qw<Exporter>;
our @EXPORT = ();
our %EXPORT_TAGS = (
- funcs => [ qw/reap localize localize_elem localize_delete unwind want_at/ ],
- words => [ qw/TOP HERE UP SUB EVAL SCOPE CALLER/ ],
- consts => [ qw/SU_THREADSAFE/ ],
+ funcs => [ qw<
+ reap
+ localize localize_elem localize_delete
+ unwind want_at
+ uplevel
+ uid validate_uid
+ > ],
+ words => [ qw<TOP HERE UP SUB EVAL SCOPE CALLER> ],
+ consts => [ qw<SU_THREADSAFE> ],
);
our @EXPORT_OK = map { @$_ } values %EXPORT_TAGS;
$EXPORT_TAGS{'all'} = [ @EXPORT_OK ];
Some rare oddities may still happen when running inside the debugger.
It may help to use a perl higher than 5.8.9 or 5.10.0, as they contain some context-related fixes.
+Calling C<goto> to replace an L</uplevel>'d code frame does not work :
+
+=over 4
+
+=item *
+
+for a C<perl> older than the 5.8 series ;
+
+=item *
+
+for a C<DEBUGGING> C<perl> run with debugging flags set (as in C<perl -D ...>) ;
+
+=item *
+
+when the runloop callback is replaced by another module.
+
+=back
+
+In those three cases, L</uplevel> will look for a C<goto &sub> statement in its callback and, if there is one, throw an exception before executing the code.
+
+Moreover, in order to handle C<goto> statements properly, L</uplevel> currently has to suffer a run-time overhead proportional to the size of the the callback in every case (with a small ratio), and proportional to the size of B<all> the code executed as the result of the L</uplevel> call (including subroutine calls inside the callback) when a C<goto> statement is found in the L</uplevel> callback.
+Despite this shortcoming, this XS version of L</uplevel> should still run way faster than the pure-Perl version from L<Sub::Uplevel>.
+
=head1 DEPENDENCIES
L<XSLoader> (standard since perl 5.006).
=head1 SEE ALSO
+L<perlfunc/local>, L<perlsub/"Temporary Values via local()">.
+
L<Alias>, L<Hook::Scope>, L<Scope::Guard>, L<Guard>.
+L<Sub::Uplevel>.
+
L<Continuation::Escape> is a thin wrapper around L<Scope::Upper> that gives you a continuation passing style interface to L</unwind>.
It's easier to use, but it requires you to have control over the scope where you want to return.
+L<Scope::Escape>.
+
=head1 AUTHOR
Vincent Pit, C<< <perl at profvince.com> >>, L<http://www.profvince.com>.
=head1 COPYRIGHT & LICENSE
-Copyright 2008,2009,2010 Vincent Pit, all rights reserved.
+Copyright 2008,2009,2010,2011 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.