Accept lvalue subroutines as a useful feature.

Support for lvalue subroutines has been stable and reliable for more
than 10 years. Despite this, they are still marked as being
experimental.

This patch removes the 'experimental' warnings from the docs, and
adjusts the description accordingly.

1 files changed, 10 insertions, 34 deletions

diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 81dbfa1a22..54f782cc61 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -732,16 +732,12 @@ also accepted.
 =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;
+	$val;		# or "return $val;"
     }
     sub nomod {
 	$val;
@@ -766,38 +762,18 @@ 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.
+Lvalue subroutines are convenient, but there are some things to keep
+in mind.
 
-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;
+You can only return scalar lvalues.
 
-    my $some_array_ref = [];	# protected by mutators ??
+When used with objects, they violate encapsulation. A normal mutator
+can check the supplied argument before setting the attribute it is
+protecting, an lvalue subroutine cannot.
 
-    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
+Lvalue subroutines are most valuable to contruct simple data
+structures that do not require any special processing when storing and
+retrieving the values.
 
 =head2 Passing Symbol Table Entries (typeglobs)
 X<typeglob> X<*>