-=head2 C<localize $what, $value, $context>
+=head2 C<localize>
+
+ localize $what, $value;
+ localize $what, $value, $context;
-=head2 C<localize_elem $what, $key, $value, $context>
+=head2 C<localize_elem>
+
+ localize_elem $what, $key, $value;
+ 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>.
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.
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.
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.
-=head2 C<localize_delete $what, $key, $context>
+=head2 C<localize_delete>
+
+ localize_delete $what, $key;
+ localize_delete $what, $key, $context;
-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 subroutine, eval or format context pointed by or just above C<$context>, and immediately restart the program flow at this point - thus effectively returning C<@values> to an upper scope.
+If C<@values> is empty, then the C<$context> parameter is optional and defaults to the current context (making the call equivalent to a bare C<return;>) ; otherwise it is mandatory.
-=head2 C<uplevel $code, @args, $context>
+=head2 C<uplevel>
+
+ my @ret = uplevel { ...; return @ret };
+ my @ret = uplevel { my @args = @_; ...; return @ret } @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.
+Executes the code reference C<$callback> 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.
my @inverses = target(1, 2, 4); # @inverses contains (0, 0.5, 0.25)
my $count = target(1, 2, 4); # $count is 3
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 :
L<Sub::Uplevel> also implements a pure-Perl version of C<uplevel>.
Both are identical, with the following caveats :
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.
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.
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>.
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>.
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>.
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.
-Copyright 2008,2009,2010,2011 Vincent Pit, all rights reserved.
+Copyright 2008,2009,2010,2011,2012 Vincent Pit, all rights reserved.