+ 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' => HERE;
+
+ will set $x to a reference to the string 'foo'. Other sigils ('@',
+ '%', '&' and '*') require $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 "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 "localize" call was compiled. For example,
+
+ {
+ package Scope;
+ sub new { localize '$tag', $_[0] => UP }
+ }
+
+ {
+ package Tool;
+ {
+ Scope->new;
+ ...
+ }
+ }
+
+ will localize $Tool::tag and not $Scope::tag. If you want the other
+ behaviour, you just have to specify $what as a glob or a qualified
+ name.
+
+ Note that if $what is a string denoting a variable that wasn't
+ declared beforehand, the relevant slot will be vivified as needed
+ and won't be deleted from the glob when the localization ends. This
+ situation never arises with "local" because it only compiles when
+ the localized variable is already declared. Although I believe it
+ shouldn't be a problem as glob slots definedness is pretty much an
+ implementation detail, this behaviour may change in the future if
+ proved harmful.
+
+ "localize_elem"
+ localize_elem $what, $key, $value;
+ localize_elem $what, $key, $value, $context;
+
+ Introduces a "local $what[$key] = $value" or "local $what{$key} =
+ $value" delayed to the time of first return into the upper scope denoted
+ by $context. Unlike "localize", $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, "localize_elem" will throw
+ an exception. $key is either an array index or a hash key, depending of
+ which kind of variable you localize.
+
+ If $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.
+
+ "localize_delete $what, $key, $context"
+ Introduces the deletion of a variable or an array/hash element delayed
+ to the time of first return into the upper scope denoted by $context.
+ $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"
+ unwind @values;
+ unwind @values, $context;
+
+ Returns @values *from* the context pointed by $context, i.e. from the
+ subroutine, eval or format at or just above $context, and immediately
+ restart the program flow at this point - thus effectively returning to
+ an upper scope.
+
+ The upper context isn't coerced onto @values, which is hence always
+ evaluated in list context. This means that
+
+ my $num = sub {
+ my @a = ('a' .. 'z');
+ unwind @a => HERE;
+ # not reached
+ }->();
+
+ will set $num to 'z'. You can use "want_at" to handle these cases.
+
+ "want_at"
+ my $want = want_at;
+ my $want = want_at $context;
+
+ Like "wantarray", but for the subroutine/eval/format at or just above
+ $context.
+
+ The previous example can then be "corrected" :
+
+ my $num = sub {
+ my @a = ('a' .. 'z');
+ unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
+ # not reached
+ }->();
+
+ will rightfully set $num to 26.
+
+ "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 $code with arguments @args as if it were
+ located at the subroutine stack frame pointed by $context, effectively
+ fooling "caller" and "die" into believing that the call actually
+ happened higher in the stack. The code is executed in the context of the
+ "uplevel" call, and what it returns is returned as-is by "uplevel".
+
+ sub target {
+ faker(@_);
+ }
+
+ sub faker {
+ uplevel {
+ map { 1 / $_ } @_;
+ } @_ => CALLER(1);
+ }