Re: [PATCH] Tests are good

[perl5.git] / pod / perlop.pod

diff --git a/pod/perlop.pod b/pod/perlop.pod
index 1dd564e..1b5d3e7 100644 (file)
--- a/pod/perlop.pod
+++ b/pod/perlop.pod
@@ -664,6 +664,7 @@ any pair of delimiters you choose.
                qr{}          Pattern             yes*
                 s{}{}      Substitution          yes*
                tr{}{}    Transliteration         no (but see below)
+        <<EOF                 here-doc            yes*
 
        * unless the delimiter is ''.
 
@@ -694,9 +695,8 @@ from the next line.  This allows you to write:
     s {foo}  # Replace foo
       {bar}  # with bar.
 
-For constructs that do interpolate, variables beginning with "C<$>"
-or "C<@>" are interpolated, as are the following escape sequences.  Within
-a transliteration, the first eleven of these sequences may be used.
+The following escape sequences are available in constructs that interpolate
+and in transliterations.
 
     \t         tab             (HT, TAB)
     \n         newline         (NL)
@@ -711,6 +711,9 @@ a transliteration, the first eleven of these sequences may be used.
     \c[                control char    (ESC)
     \N{name}   named char
 
+The following escape sequences are available in constructs that interpolate
+but not in transliterations.
+
     \l         lowercase next char
     \u         uppercase next char
     \L         lowercase till \E
@@ -736,14 +739,15 @@ and although they often accept just C<"\012">, they seldom tolerate just
 C<"\015">.  If you get in the habit of using C<"\n"> for networking,
 you may be burned some day.
 
-Subscripted variables such as C<$a[3]> or C<$href->{key}[0]> are also
-interpolated, as are array and hash slices.    But method calls
-such as C<$obj->meth> are not interpolated.
+For constructs that do interpolate, variables beginning with "C<$>"
+or "C<@>" are interpolated.  Subscripted variables such as C<$a[3]> or
+C<$href->{key}[0]> are also interpolated, as are array and hash slices.
+But method calls such as C<$obj->meth> are not.
 
 Interpolating an array or slice interpolates the elements in order,
 separated by the value of C<$">, so is equivalent to interpolating
-C<join $", @array>.    "Punctuation" arrays such C<@+> are not
-interpolated.
+C<join $", @array>.    "Punctuation" arrays such as C<@+> are only
+interpolated if the name is enclosed in braces C<@{+}>.
 
 You cannot include a literal C<$> or C<@> within a C<\Q> sequence. 
 An unescaped C<$> or C<@> interpolates the corresponding variable, 
@@ -1340,6 +1344,98 @@ must use an eval():
 
     eval "tr/$oldlist/$newlist/, 1" or die $@;
 
+=item <<EOF
+
+A line-oriented form of quoting is based on the shell "here-document"
+syntax.  Following a C<< << >> you specify a string to terminate
+the quoted material, and all lines following the current line down to
+the terminating string are the value of the item.  The terminating
+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, 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
+    The price is $Price.
+    EOF
+
+       print << `EOC`; # execute commands
+    echo hi there
+    echo lo there
+    EOC
+
+       print <<"foo", <<"bar"; # you can stack them
+    I said foo.
+    foo
+    I said bar.
+    bar
+
+       myfunc(<< "THIS", 23, <<'THAT');
+    Here's a line
+    or two.
+    THIS
+    and here's another.
+    THAT
+
+Just don't forget that you have to put a semicolon on the end
+to finish the statement, as Perl doesn't know you're not going to
+try to do this:
+
+       print <<ABC
+    179231
+    ABC
+       + 20;
+
+If you want your here-docs to be indented with the 
+rest of the code, you'll need to remove leading whitespace
+from each line manually:
+
+    ($quote = <<'FINIS') =~ s/^\s+//gm;
+       The Road goes ever on and on, 
+       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.
+
 =back
 
 =head2 Gory details of parsing quoted constructs