Integrate with Sarathy.

p4raw-id: //depot/cfgperl@4091

5 files changed, 79 insertions, 6 deletions

diff --git a/pod/perldelta.pod b/pod/perldelta.pod
index 353c62d55f..69beac3e99 100644
--- a/pod/perldelta.pod
+++ b/pod/perldelta.pod
@@ -718,6 +718,13 @@ of a subroutine attribute, and it wasn't a semicolon or the start of a
 block.  Perhaps you terminated the parameter list of the previous attribute
 too soon.
 
+=item /%s/ should probably be written as "%s"
+
+(W) You have used a pattern where Perl expected to find a string,
+like in the first argument to C<join>.  Perl will treat the true
+or false result of matching the pattern against $_ as the string,
+which is probably not what you had in mind.
+
 =head1 Obsolete Diagnostics
 
 Todo.
diff --git a/pod/perldiag.pod b/pod/perldiag.pod
index 60a901ea03..1c07a31fa6 100644
--- a/pod/perldiag.pod
+++ b/pod/perldiag.pod
@@ -112,6 +112,13 @@ your signed integers.  See L<perlfunc/unpack>.
 by Perl.  This combination appears in an interpolated variable or a 
 C<'>-delimited regular expression.
 
+=item /%s/ should probably be written as "%s"
+
+(W) You have used a pattern where Perl expected to find a string,
+like in the first argument to C<join>.  Perl will treat the true
+or false result of matching the pattern against $_ as the string,
+which is probably not what you had in mind.
+
 =item %s (...) interpreted as function
 
 (W) You've run afoul of the rule that says that any list operator followed
@@ -866,6 +873,11 @@ to exist.
 (F) You aren't allowed to assign to the item indicated, or otherwise try to
 change it, such as with an auto-increment.
 
+=item Can't modify non-lvalue subroutine call
+
+(F) Subroutines used in lvalue context should be marked as such, see
+L<perlsub/"Lvalue subroutines">.
+
 =item Can't modify nonexistent substring
 
 (P) The internal routine that does assignment to a substr() was handed
@@ -950,6 +962,12 @@ of suidperl.
 (F) The return statement was executed in mainline code, that is, where
 there was no subroutine call to return out of.  See L<perlsub>.
 
+=item Can't return %s from lvalue subroutine
+
+(F) Perl detected an attempt to return illegal lvalues (such
+as temporary or readonly values) from a subroutine used as an lvalue.
+This is not allowed.
+
 =item Can't stat script "%s"
 
 (P) For some reason you can't fstat() the script even though you have
@@ -1713,6 +1731,12 @@ effective uids or gids failed.
 (W) You tried to do a listen on a closed socket.  Did you forget to check
 the return value of your socket() call?  See L<perlfunc/listen>.
 
+=item Lvalue subs returning %s not implemented yet
+
+(F) Due to limitations in the current implementation, array and hash
+values cannot be returned in subroutines used in lvalue context.
+See L<perlsub/"Lvalue subroutines">.
+
 =item Method for operation %s not found in package %s during blessing
 
 (F) An attempt was made to specify an entry in an overloading table that
diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod
index d420059d4c..0d47260e10 100644
--- a/pod/perlfunc.pod
+++ b/pod/perlfunc.pod
@@ -2064,7 +2064,8 @@ separated by the value of EXPR, and returns that new string.  Example:
 
     $rec = join(':', $login,$passwd,$uid,$gid,$gcos,$home,$shell);
 
-See L</split>.
+Beware that unlike C<split>, C<join> doesn't take a pattern as its
+first argument.  Compare L</split>.
 
 =item keys HASH
 
@@ -4103,6 +4104,7 @@ and the conversion letter:
            for integer
    l       interpret integer as C type "long" or "unsigned long"
    h       interpret integer as C type "short" or "unsigned short"
+           If no flags, interpret integer as C type "int" or "unsigned"
 
 There is also one Perl-specific flag:
 
@@ -4120,7 +4122,7 @@ See L<perllocale>.
 
 If Perl understands "quads" (64-bit integers) (this requires
 either that the platform natively supports quads or that Perl
-has been specifically compiled to support quads), the flags
+has been specifically compiled to support quads), the characters
 
 	d u o x X b i D U O
 
diff --git a/pod/perlsub.pod b/pod/perlsub.pod
index 47f507f28d..2beb3dea55 100644
--- a/pod/perlsub.pod
+++ b/pod/perlsub.pod
@@ -611,6 +611,45 @@ Perl will print
 The behavior of local() on non-existent members of composite
 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.
+
+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 {
+	$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.
+
+The current implementation does not allow arrays and hashes to be
+returned from lvalue subroutines directly.  You may return a
+reference instead.  This restriction may be lifted in future.
+
 =head2 Passing Symbol Table Entries (typeglobs)
 
 B<WARNING>: The mechanism described in this section was originally
diff --git a/pod/perlsyn.pod b/pod/perlsyn.pod
index d08a5f946f..680ecb9ad9 100644
--- a/pod/perlsyn.pod
+++ b/pod/perlsyn.pod
@@ -155,10 +155,11 @@ C<if> an C<else> goes with.  If you use C<unless> in place of C<if>,
 the sense of the test is reversed.
 
 The C<while> statement executes the block as long as the expression is
-true (does not evaluate to the null string (C<"">) or C<0> or C<"0")>.  The LABEL is
-optional, and if present, consists of an identifier followed by a colon.
-The LABEL identifies the loop for the loop control statements C<next>,
-C<last>, and C<redo>.  If the LABEL is omitted, the loop control statement
+true (does not evaluate to the null string (C<""> or C<0> or C<"0">).
+The LABEL is optional, and if present, consists of an identifier followed
+by a colon.  The LABEL identifies the loop for the loop control
+statements C<next>, C<last>, and C<redo>.
+If the LABEL is omitted, the loop control statement
 refers to the innermost enclosing loop.  This may include dynamically
 looking back your call-stack at run time to find the LABEL.  Such
 desperate behavior triggers a warning if you use the B<-w> flag.