X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlsub.pod;h=ce3b120633e87370984d99a71e034999785b5f78;hb=6f12eb6d2a1dfaf441504d869b27d2e40ef4966a;hp=b929c988d6901d595b7e91e1fdd74deb72f58ccb;hpb=e855abcaff9a6a855a1a816cf0034aa0ebf64476;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index b929c98..ce3b120 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -169,7 +169,7 @@ Do not, however, be tempted to do this:
 
 Like the flattened incoming parameter list, the return list is also
 flattened on return.  So all you have managed to do here is stored
-everything in C<@a> and made C<@b> an empty list.  See 
+everything in C<@a> and made C<@b> empty.  See 
 L<Pass by Reference> for alternatives.
 
 A subroutine may be called using an explicit C<&> prefix.  The
@@ -220,9 +220,9 @@ Synopsis:
     my @oof = @bar;	# declare @oof lexical, and init it
     my $x : Foo = $y;	# similar, with an attribute applied
 
-B<WARNING>: The use of attribute lists on C<my> declarations is
-experimental.  This feature should not be relied upon.  It may
-change or disappear in future releases of Perl.  See L<attributes>.
+B<WARNING>: The use of attribute lists on C<my> declarations is still
+evolving.  The current semantics and interface are subject to change.
+See L<attributes> and L<Attribute::Handlers>.
 
 The C<my> operator declares the listed variables to be lexically
 confined to the enclosing block, conditional (C<if/unless/elsif/else>),
@@ -327,12 +327,12 @@ the scope of $answer extends from its declaration through the rest
 of that conditional, including any C<elsif> and C<else> clauses, 
 but not beyond it.
 
-B<NOTE:> None of the foregoing text applies to C<if/unless>,
-C<while/until> or C<for> modifiers appended to simple statements. Such
-modifiers are not control structures and have no effect on scoping. The
-use of such modifiers in conjunction with C<my> is best avoided, as it may
-have unexpected effects.  A future release of Perl may define precise
-semantics for constructs such as C<my $foo = 1 if $bar>.
+B<NOTE:> The behaviour of a C<my> statement modified with a statement
+modifier conditional or loop construct (e.g. C<my $x if ...>) is
+B<undefined>.  The value of the C<my> variable may be C<undef>, any
+previously assigned value, or possibly anything else.  Don't rely on
+it.  Future versions of perl might do something different from the
+version of perl you try it out on.  Here be dragons.
 
 The C<foreach> loop defaults to scoping its index variable dynamically
 in the manner of C<local>.  However, if the index variable is
@@ -563,6 +563,13 @@ hash to some other implementation:
     }
     [..%ahash back to its initial tied self again..]
 
+B<WARNING> The code example above 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<perldelta/"Localising Tied Arrays and Hashes Is Broken"> for more
+details.
+
 As another example, a custom implementation of C<%ENV> might look
 like this:
 
@@ -615,14 +622,15 @@ types is subject to change in future.
 
 =head2 Lvalue subroutines
 
-B<WARNING>: Lvalue subroutines are still experimental and the implementation
-may change in future versions of Perl.
+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 {
@@ -648,6 +656,39 @@ and in:
 
 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
+
 =head2 Passing Symbol Table Entries (typeglobs)
 
 B<WARNING>: The mechanism described in this section was originally
@@ -727,7 +768,7 @@ table entries:
 
     sub ioqueue {
         local  (*READER, *WRITER);    # not my!
-        pipe    (READER,  WRITER);    or die "pipe: $!";
+        pipe    (READER,  WRITER)     or die "pipe: $!";
         return (*READER, *WRITER);
     }
     ($head, $tail) = ioqueue();
@@ -1319,7 +1360,7 @@ parsed and invoked:
     use attributes __PACKAGE__, \&plugh, q[Ugly('\(")], 'Bad';
 
 For further details on attribute lists and their manipulation,
-see L<attributes>.
+see L<attributes> and L<Attribute::Handlers>.
 
 =head1 SEE ALSO