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>.
Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
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>.
Unlike L</localize>, C<$what> must be a string and the type of localization is inferred from its sigil.
Returns C<@values> I<from> the context pointed by C<$context>, i.e. from the subroutine, eval or format at or just above C<$context>, and immediately restart the program flow at this point - thus effectively returning to an upper scope.
Returns C<@values> I<from> the context pointed by C<$context>, i.e. from the subroutine, eval or format at or just above C<$context>, and immediately restart the program flow at this point - thus effectively returning to an upper scope.
Like C<wantarray>, but for the subroutine/eval/format at or just above C<$context>.
Like C<wantarray>, but for the subroutine/eval/format at or just above C<$context>.
@@ -312,6+331,11 @@ will rightfully set C<$num> to C<26>.
=head2 C<uplevel $code, @args, $context>
=head2 C<uplevel $code, @args, $context>
+ my @ret = uplevel { ...; return @ret };
+ my @ret = uplevel { my @args = @_; ...; return @ret } @args;
+ my @ret = uplevel { ... } @args, $context;
+ my @ret = &uplevel($callback, @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>.
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>.
@@ -379,7+403,10 @@ A simple wrapper lets you mimic the interface of L<Sub::Uplevel/uplevel> :
Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
Albeit the three exceptions listed above, it passes all the tests of L<Sub::Uplevel>.
-=head2 C<uid $context>
+=head2 C<uid>
+
+ my $uid = uid;
+ my $uid = 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.
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.
@@ -424,7+451,9 @@ The UIDs are not guaranteed to be numbers, so you must use the C<eq> operator to
To check whether a given UID is valid, you can use the L</validate_uid> function.
To check whether a given UID is valid, you can use the L</validate_uid> function.
-=head2 C<validate_uid $uid>
+=head2 C<validate_uid>
+
+ my $is_valid = 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).
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).
@@ -458,10+487,14 @@ True iff the module could have been built when thread-safety features.
=head3 C<TOP>
=head3 C<TOP>
+ my $top_context = TOP;
+
Returns the context that currently represents the highest scope.
=head3 C<HERE>
Returns the context that currently represents the highest scope.
For any of those functions, C<$from> is expected to be a context.
When omitted, it defaults to the the current context.
For any of those functions, C<$from> is expected to be a context.
When omitted, it defaults to the the current context.
-=head3 C<UP $from>
+=head3 C<UP>
+
+ my $upper_context = UP;
+ my $upper_context = UP $from;
The context of the scope just above C<$from>.
The context of the scope just above C<$from>.
-=head3 C<SUB $from>
+=head3 C<SUB>
+
+ my $sub_context = SUB;
+ my $sub_context = SUB $from;
The context of the closest subroutine above C<$from>.
Note that C<$from> is returned if it is already a subroutine context ; hence C<SUB SUB == SUB>.
The context of the closest subroutine above C<$from>.
Note that C<$from> is returned if it is already a subroutine context ; hence C<SUB SUB == SUB>.
-=head3 C<EVAL $from>
+=head3 C<EVAL>
+
+ my $eval_context = EVAL;
+ my $eval_context = EVAL $from;
The context of the closest eval above C<$from>.
Note that C<$from> is returned if it is already an eval context ; hence C<EVAL EVAL == EVAL>.
The context of the closest eval above C<$from>.
Note that C<$from> is returned if it is already an eval context ; hence C<EVAL EVAL == EVAL>.
@@ -488,11+530,17 @@ Note that C<$from> is returned if it is already an eval context ; hence C<EVAL E
Here, C<$level> should denote a number of scopes above the current one.
When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
Here, C<$level> should denote a number of scopes above the current one.
When omitted, it defaults to C<0> and those functions return the same context as L</HERE>.
-=head3 C<SCOPE $level>
+=head3 C<SCOPE>
+
+ my $context = SCOPE;
+ my $context = SCOPE $level;
The C<$level>-th upper context, regardless of its type.
The C<$level>-th upper context, regardless of its type.
-=head3 C<CALLER $level>
+=head3 C<CALLER>
+
+ my $context = CALLER;
+ my $context = CALLER $level;
The context of the C<$level>-th upper subroutine/eval/format.
It kind of corresponds to the context represented by C<caller $level>, but while e.g. C<caller 0> refers to the caller context, C<CALLER 0> will refer to the top scope in the current context.
The context of the C<$level>-th upper subroutine/eval/format.
It kind of corresponds to the context represented by C<caller $level>, but while e.g. C<caller 0> refers to the caller context, C<CALLER 0> will refer to the top scope in the current context.
@@ -507,13+555,13 @@ Where L</reap> fires depending on the C<$cxt> :
{
reap \&cleanup => $cxt;
...
{
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> :
...
Where L</localize>, L</localize_elem> and L</localize_delete> act depending on the C<$cxt> :
@@ -523,19+571,19 @@ Where L</localize>, L</localize_elem> and L</localize_delete> act depending on t
sub {
{
localize '$x' => 1 => $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>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
...
Where L</unwind>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
@@ -544,15+592,15 @@ Where L</unwind>, L</want_at> and L</uplevel> point to depending on the C<$cxt>:
projects / perl / modules / Scope-Upper.git / blobdiff