+ 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"
+ localize_delete $what, $key;
+ 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 respectively "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;
+ unwind @values, $context;
+
+ Returns @values *from* the subroutine, eval or format context pointed by
+ or just above $context, and immediately restarts the program flow at
+ this point - thus effectively returning @values to an upper scope. If
+ @values is empty, then the $context parameter is optional and defaults
+ to the current context (making the call equivalent to a bare "return;")
+ ; otherwise it is mandatory.
+
+ 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.
+
+ "yield"
+ yield;
+ yield @values, $context;
+
+ Returns @values *from* the context pointed by or just above $context,
+ and immediately restarts the program flow at this point. If @values is
+ empty, then the $context parameter is optional and defaults to the
+ current context ; otherwise it is mandatory.
+
+ "yield" differs from "unwind" in that it can target *any* upper scope
+ (besides a "s///e" substitution context) and not necessarily a sub, an
+ eval or a format. Hence you can use it to return values from a "do" or a
+ "map" block :
+
+ my $now = do {
+ local $@;
+ eval { require Time::HiRes } or yield time() => HERE;
+ Time::HiRes::time();
+ };
+
+ my @uniq = map {
+ yield if $seen{$_}++; # returns the empty list from the block
+ ...
+ } @things;
+
+ Like for "unwind", the upper context isn't coerced onto @values. You can
+ use the fifth value returned by "context_info" to handle context
+ coercion.
+
+ "leave"
+ leave;
+ leave @values;
+
+ Immediately returns @values from the current block, whatever it may be
+ (besides a "s///e" substitution context). "leave" is actually a synonym
+ for "yield HERE", while "leave @values" is a synonym for "yield @values,
+ HERE".
+
+ Like for "yield", you can use the fifth value returned by "context_info"
+ to handle context coercion.
+
+ "want_at"
+ my $want = want_at;
+ my $want = want_at $context;
+
+ Like "wantarray" in perlfunc, but for the subroutine, eval or format
+ context located at or just above $context.
+
+ It can be used to revise the example showed in "unwind" :
+
+ my $num = sub {
+ my @a = ('a' .. 'z');
+ unwind +(want_at(HERE) ? @a : scalar @a) => HERE;
+ # not reached
+ }->();
+
+ will rightfully set $num to 26.