X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperldata.pod;h=315f716ed876a2b7ad24e2738709f877806a97fb;hb=de4864e4e7ced178416488fa2591227064c3222d;hp=70ab1615f213c88dc5002745710b78f2b4855893;hpb=4b19af017623bfa3bb72bb164598a517f586e0d3;p=p5sagit%2Fp5-mst-13.2.git

diff --git a/pod/perldata.pod b/pod/perldata.pod
index 70ab161..315f716 100644
--- a/pod/perldata.pod
+++ b/pod/perldata.pod
@@ -209,9 +209,9 @@ with a regular expression (as documented in L<perlre>).
 	unless /^([+-]?)(?=\d|\.\d)\d*(\.\d*)?([Ee]([+-]?\d+))?$/;
 
 The length of an array is a scalar value.  You may find the length
-of array @days by evaluating C<$#days>, as in B<csh>.  Technically
-speaking, this isn't the length of the array; it's the subscript
-of the last element, since there is ordinarily a 0th element.
+of array @days by evaluating C<$#days>, as in B<csh>.  However, this
+isn't the length of the array; it's the subscript of the last element,
+which is a different value since there is ordinarily a 0th element.
 Assigning to C<$#days> actually changes the length of the array.
 Shortening an array this way destroys intervening values.  Lengthening
 an array that was previously shortened does not recover values
@@ -413,20 +413,20 @@ string may be either an identifier (a word), or some quoted text.  If
 quoted, the type of quotes you use determines the treatment of the
 text, just as in regular quoting.  An unquoted identifier works like
 double quotes.  There must be no space between the C<< << >> and
-the identifier.  (If you put a space it will be treated as a null
-identifier, which is valid, and matches the first empty line.)  The
-terminating string must appear by itself (unquoted and with no
-surrounding whitespace) on the terminating line.
+the identifier, unless the identifier is quoted.  (If you put a space it
+will be treated as a null identifier, which is valid, and matches the first
+empty line.)  The terminating string must appear by itself (unquoted and
+with no surrounding whitespace) on the terminating line.
 
 	print <<EOF;
     The price is $Price.
     EOF
 
-	print <<"EOF";	# same as above
+	print << "EOF";	# same as above
     The price is $Price.
     EOF
 
-	print <<`EOC`;	# execute commands
+	print << `EOC`;	# execute commands
     echo hi there
     echo lo there
     EOC
@@ -437,7 +437,7 @@ surrounding whitespace) on the terminating line.
     I said bar.
     bar
 
-	myfunc(<<"THIS", 23, <<'THAT');
+	myfunc(<< "THIS", 23, <<'THAT');
     Here's a line
     or two.
     THIS
@@ -462,6 +462,39 @@ from each line manually:
 	down from the door where it began.
     FINIS
 
+If you use a here-doc within a delimited construct, such as in C<s///eg>,
+the quoted material must come on the lines following the final delimiter.
+So instead of
+
+    s/this/<<E . 'that'
+    the other
+    E
+     . 'more '/eg;
+
+you have to write
+
+    s/this/<<E . 'that' 
+     . 'more '/eg; 
+    the other 
+    E 
+
+If the terminating identifier is on the last line of the program, you
+must be sure there is a newline after it; otherwise, Perl will give the
+warning B<Can't find string terminator "END" anywhere before EOF...>.
+
+Additionally, the quoting rules for the identifier are not related to
+Perl's quoting rules -- C<q()>, C<qq()>, and the like are not supported
+in place of C<''> and C<"">, and the only interpolation is for backslashing
+the quoting character:
+
+    print << "abc\"def";
+    testing...
+    abc"def
+
+Finally, quoted strings cannot span multiple lines.  The general rule is
+that the identifier must be a string literal.  Stick with that, and you
+should be safe.
+
 =head2 List value constructors
 
 List values are denoted by separating individual values by commas
@@ -524,6 +557,15 @@ has no effect.  Thus ((),(),()) is equivalent to ().  Similarly,
 interpolating an array with no elements is the same as if no
 array had been interpolated at that point.
 
+This interpolation combines with the facts that the opening
+and closing parentheses are optional (except necessary for
+precedence) and lists may end with an optional comma to mean that
+multiple commas within lists are legal syntax. The list C<1,,3> is a
+concatenation of two lists, C<1,> and C<3>, the first of which ends
+with that optional comma.  C<1,,3> is C<(1,),(3)> is C<1,3> (And
+similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.)  Not that
+we'd advise you to use this obfuscation.
+
 A list value may also be subscripted like a normal array.  You must
 put the list in parentheses to avoid ambiguity.  For example: