Re: pod patches.

Message-ID: <3CE90F7A.3070309@divsol.com>

(with Philip Newton's tweaks)

p4raw-id: //depot/perl@16710

1 files changed, 36 insertions, 2 deletions

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index cff3edadfa..7bee99959d 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -615,14 +615,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 +649,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