+=head3 Localization of special variables
+X<local, special variable>
+
+If you localize a special variable, you'll be giving a new value to it,
+but its magic won't go away. That means that all side-effects related
+to this magic still work with the localized value.
+
+This feature allows code like this to work :
+
+ # Read the whole contents of FILE in $slurp
+ { local $/ = undef; $slurp = <FILE>; }
+
+Note, however, that this restricts localization of some values ; for
+example, the following statement dies, as of perl 5.9.0, with an error
+I<Modification of a read-only value attempted>, because the $1 variable is
+magical and read-only :
+
+ local $1 = 2;
+
+Similarly, but in a way more difficult to spot, the following snippet will
+die in perl 5.9.0 :
+
+ sub f { local $_ = "foo"; print }
+ for ($1) {
+ # now $_ is aliased to $1, thus is magic and readonly
+ f();
+ }
+
+See next section for an alternative to this situation.
+
+B<WARNING>: Localization of tied arrays and hashes does not currently
+work as described.
+This will be fixed in a future release of Perl; in the meantime, avoid
+code that relies on any particular behaviour of localising tied arrays
+or hashes (localising individual elements is still okay).
+See L<perl58delta/"Localising Tied Arrays and Hashes Is Broken"> for more
+details.
+X<local, tie>
+
+=head3 Localization of globs
+X<local, glob> X<glob>
+
+The construct
+
+ local *name;
+
+creates a whole new symbol table entry for the glob C<name> in the
+current package. That means that all variables in its glob slot ($name,
+@name, %name, &name, and the C<name> filehandle) are dynamically reset.
+
+This implies, among other things, that any magic eventually carried by
+those variables is locally lost. In other words, saying C<local */>
+will not have any effect on the internal value of the input record
+separator.
+
+Notably, if you want to work with a brand new value of the default scalar
+$_, and avoid the potential problem listed above about $_ previously
+carrying a magic value, you should use C<local *_> instead of C<local $_>.
+As of perl 5.9.1, you can also use the lexical form of C<$_> (declaring it
+with C<my $_>), which avoids completely this problem.
+
+=head3 Localization of elements of composite types
+X<local, composite type element> X<local, array element> X<local, hash element>
+
+It's also worth taking a moment to explain what happens when you
+C<local>ize a member of a composite type (i.e. an array or hash element).
+In this case, the element is C<local>ized I<by name>. This means that
+when the scope of the C<local()> ends, the saved value will be
+restored to the hash element whose key was named in the C<local()>, or
+the array element whose index was named in the C<local()>. If that
+element was deleted while the C<local()> was in effect (e.g. by a
+C<delete()> from a hash or a C<shift()> of an array), it will spring
+back into existence, possibly extending an array and filling in the
+skipped elements with C<undef>. For instance, if you say
+
+ %hash = ( 'This' => 'is', 'a' => 'test' );
+ @ary = ( 0..5 );
+ {
+ local($ary[5]) = 6;
+ local($hash{'a'}) = 'drill';
+ while (my $e = pop(@ary)) {
+ print "$e . . .\n";
+ last unless $e > 3;
+ }
+ if (@ary) {
+ $hash{'only a'} = 'test';
+ delete $hash{'a'};
+ }
+ }
+ print join(' ', map { "$_ $hash{$_}" } sort keys %hash),".\n";
+ print "The array has ",scalar(@ary)," elements: ",
+ join(', ', map { defined $_ ? $_ : 'undef' } @ary),"\n";
+
+Perl will print
+
+ 6 . . .
+ 4 . . .
+ 3 . . .
+ This is a test only a test.
+ The array has 6 elements: 0, 1, 2, undef, undef, 5
+
+The behavior of local() on non-existent members of composite
+types is subject to change in future.
+
+=head3 Localized deletion of elements of composite types
+X<delete> X<local, composite type element> X<local, array element> X<local, hash element>
+
+You can use the C<delete local $array[$idx]> and C<delete local $hash{key}>
+constructs to delete a composite type entry for the current block and restore
+it when it ends. They return the array/hash value before the localization,
+which means that they are respectively equivalent to
+
+ do {
+ my $val = $array[$idx];
+ local $array[$idx];
+ delete $array[$idx];
+ $val
+ }
+
+and
+
+ do {
+ my $val = $hash{key};
+ local $hash{key};
+ delete $hash{key};
+ $val
+ }
+
+except that for those the C<local> is scoped to the C<do> block. Slices are
+also accepted.
+
+ my %hash = (
+ a => [ 7, 8, 9 ],
+ b => 1,
+ )
+
+ {
+ my $a = delete local $hash{a};
+ # $a is [ 7, 8, 9 ]
+ # %hash is (b => 1)
+
+ {
+ my @nums = delete local @$a[0, 2]
+ # @nums is (7, 9)
+ # $a is [ undef, 8 ]
+
+ $a[0] = 999; # will be erased when the scope ends
+ }
+ # $a is back to [ 7, 8, 9 ]
+
+ }
+ # %hash is back to its original state
+
+=head2 Lvalue subroutines
+X<lvalue> X<subroutine, lvalue>
+
+B<WARNING>: Lvalue subroutines are still experimental and the
+implementation may change in future versions of Perl.
+
+It is possible to return a modifiable value from a subroutine.
+To do this, you have to declare the subroutine to return an lvalue.
+
+ my $val;
+ sub canmod : lvalue {
+ # return $val; this doesn't work, don't say "return"
+ $val;
+ }
+ sub nomod {
+ $val;
+ }
+
+ canmod() = 5; # assigns to $val
+ nomod() = 5; # ERROR
+
+The scalar/list context for the subroutine and for the right-hand
+side of assignment is determined as if the subroutine call is replaced
+by a scalar. For example, consider:
+
+ data(2,3) = get_data(3,4);
+
+Both subroutines here are called in a scalar context, while in:
+
+ (data(2,3)) = get_data(3,4);
+
+and in:
+
+ (data(2),data(3)) = get_data(3,4);
+
+all the subroutines are called in a list context.
+
+=over 4
+
+=item Lvalue subroutines are EXPERIMENTAL
+
+They appear to be convenient, but there are several reasons to be
+circumspect.
+
+You can't use the return keyword, you must pass out the value before
+falling out of subroutine scope. (see comment in example above). This
+is usually not a problem, but it disallows an explicit return out of a
+deeply nested loop, which is sometimes a nice way out.
+
+They violate encapsulation. A normal mutator can check the supplied
+argument before setting the attribute it is protecting, an lvalue
+subroutine never gets that chance. Consider;
+
+ my $some_array_ref = []; # protected by mutators ??
+
+ sub set_arr { # normal mutator
+ my $val = shift;
+ die("expected array, you supplied ", ref $val)
+ unless ref $val eq 'ARRAY';
+ $some_array_ref = $val;
+ }
+ sub set_arr_lv : lvalue { # lvalue mutator
+ $some_array_ref;
+ }
+
+ # set_arr_lv cannot stop this !
+ set_arr_lv() = { a => 1 };
+
+=back
+