Skip to content

Commit 54c3d92

Browse files
committed
perlop: Clean up here-doc documentation
The documentation for indented here-docs had a bunch of duplicated concepts with the documentation of plain here-docs. This commit melds them into a single coherent section.
1 parent f9d1ecd commit 54c3d92

File tree

1 file changed

+177
-116
lines changed

1 file changed

+177
-116
lines changed

pod/perlop.pod

Lines changed: 177 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -2875,85 +2875,151 @@ must use an C<eval()>:
28752875

28762876
eval "tr/$oldlist/$newlist/, 1" or die $@;
28772877

2878-
=item C<< <<I<EOF> >>
2879-
X<here-doc> X<heredoc> X<here-document> X<<< << >>>
2878+
=back
2879+
2880+
=head3 Here-docs
2881+
X<here-doc> X<here-docs> X<heredoc> X<here-document> X<<< << >>>
2882+
2883+
=over 4
2884+
2885+
=item C<< <<I<EOT> >>
2886+
2887+
=item C<< <<~I<EOT> >>
28802888

28812889
A line-oriented form of quoting is based on the shell "here-document"
28822890
syntax. Following a C<< << >> you specify a string to terminate
28832891
the quoted material, and all lines following the current line down to
28842892
the terminating string are the value of the item.
28852893

2886-
Prefixing the terminating string with a C<~> specifies that you
2887-
want to use L</Indented Here-docs> (see below).
2894+
An example is
28882895

2889-
The terminating string may be either an identifier (a word), or some
2890-
quoted text. An unquoted identifier works like double quotes.
2891-
There may not be a space between the C<< << >> and the identifier,
2892-
unless the identifier is explicitly quoted. The terminating string
2893-
must appear by itself (unquoted and with no surrounding whitespace)
2894-
on the terminating line.
2896+
my $endng = <<WHIMPER;
2897+
This is the way the text ends.
2898+
This is the way the text ends.
2899+
Not with a bang, but with a
2900+
WHIMPER
28952901

2896-
If the terminating string is quoted, the type of quotes used determine
2897-
the treatment of the text.
2902+
In this case, the terminator is an identifier, the word "WHIMPER". Most
2903+
usually, people capitalize the identifier, just so it stands out, but
2904+
this is just a convention that isn't necessary. There may not be a
2905+
space between the C<< << >> and the identifier,
28982906

2899-
=over 4
2907+
The terminator may be enclosed in quotes, as detailed below, but without
2908+
them, the text of the here-doc acts exactly as if it were double-quoted.
29002909

2901-
=item Double Quotes
2910+
my $person = 'John';
29022911

2903-
Double quotes indicate that the text will be interpolated using exactly
2904-
the same rules as normal double quoted strings.
2912+
print uc <<EOT;
2913+
Hello, $person!
2914+
And the text goes on.
2915+
EOT
29052916

2906-
print <<EOF;
2907-
The price is $Price.
2908-
EOF
2917+
This yields:
29092918

2910-
print << "EOF"; # same as above
2911-
The price is $Price.
2912-
EOF
2919+
HELLO, JOHN!
2920+
AND THE TEXT GOES ON.
29132921

2922+
The parentheses in the C<uc> function call don't have to be omitted:
29142923

2915-
=item Single Quotes
2924+
print uc(<<EOT);
2925+
Hello, $person!
2926+
And the text goes on.
2927+
EOT
29162928

2917-
Single quotes indicate the text is to be treated literally with no
2918-
interpolation of its content. This is similar to single quoted
2919-
strings except that backslashes have no special meaning, with C<\\>
2920-
being treated as two backslashes and not one as they would in every
2921-
other quoting construct.
2929+
HELLO, JOHN!
2930+
AND THE TEXT GOES ON.
29222931

2923-
Just as in the shell, a backslashed bareword following the C<<< << >>>
2924-
means the same thing as a single-quoted string does:
2932+
And you can intermix a here-document with other things:
29252933

2926-
$cost = <<'VISTA'; # hasta la ...
2927-
That'll be $10 please, ma'am.
2928-
VISTA
2934+
print <<EOT, "Followed by the next argument\n";
2935+
Hello, $person!
2936+
And the text goes on.
2937+
EOT
29292938

2930-
$cost = <<\VISTA; # Same thing!
2931-
That'll be $10 please, ma'am.
2932-
VISTA
2939+
Hello, John!
2940+
And the text goes on.
2941+
Followed by the next argument
29332942

2934-
This is the only form of quoting in perl where there is no need
2935-
to worry about escaping content, something that code generators
2936-
can and do make good use of.
2943+
And you can have multiple here-documents:
29372944

2938-
=item Backticks
2945+
print <<EOT1, <<EOT2;
2946+
Hello, $person!
2947+
And the text goes on.
2948+
EOT1
2949+
Followed by the next argument
2950+
EOT2
29392951

2940-
The content of the here doc is treated just as it would be if the
2941-
string were embedded in backticks. Thus the content is interpolated
2942-
as though it were double quoted and then executed via the shell, with
2943-
the results of the execution returned.
2952+
Hello, John!
2953+
And the text goes on.
2954+
Followed by the next argument
29442955

2945-
print << `EOC`; # execute command and get results
2946-
echo hi there
2947-
EOC
2956+
The terminator doesn't have to be a single word; it may also be some
2957+
quoted text,
29482958

2949-
=back
2959+
my $pagliaci = << "La Commedia e finita!";
2960+
A troupe comes to town to perform a play, a comedy. The lead actress
2961+
and lead actor are in an unhappy marriage. On stage, he stabs her
2962+
for real; then he stabs her lover who has rushed from the audience to
2963+
defend her. Both die.
2964+
La Commedia e finita!
29502965

2951-
=over 4
2966+
When the terminator is quoted, there may be space between it and the
2967+
C<<< << >>>, as demonstrated in the example just above. Quoting rules
2968+
for it are unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the
2969+
like are not supported in place of C<""> and C<''>, and the only
2970+
interpolation is for backslashing the quoting character:
2971+
2972+
print << "abc\"def";
2973+
testing...
2974+
abc"def
2975+
2976+
The terminating string must appear by itself (unquoted and with no
2977+
surrounding whitespace) on the terminating line. And, it cannot span
2978+
multiple lines. The general rule is that the identifier must be a
2979+
string literal. Stick with that, and you should be safe.
2980+
2981+
Don't forget that you have to put a semicolon on the end to finish the
2982+
statement, as Perl doesn't know you're not going to try to do this:
2983+
2984+
print <<ABC
2985+
10
2986+
ABC
2987+
+ 20;
2988+
2989+
which prints C<30> without any line terminator.
2990+
2991+
If you want to remove the final line terminator from your here-docs,
2992+
use C<chomp()>.
2993+
2994+
chomp($string = <<'END');
2995+
This is the first line.
2996+
This second line won't end in a \n.
2997+
END
2998+
2999+
If you use a here-doc within a delimited construct, such as in C<s///eg>,
3000+
the quoted material must still come on the line following the
3001+
C<<< <<FOO >>> marker, which means it may be inside the delimited
3002+
construct:
3003+
3004+
s/this/<<E . 'that'
3005+
the other
3006+
E
3007+
. 'more '/eg;
3008+
3009+
It works this way as of Perl 5.18. Historically, it was inconsistent, and
3010+
you would have to write
29523011

2953-
=item Indented Here-docs
3012+
s/this/<<E . 'that'
3013+
. 'more '/eg;
3014+
the other
3015+
E
3016+
3017+
outside of string evals.
29543018

2955-
The here-doc modifier C<~> allows you to indent your here-docs to make
2956-
the code more readable:
3019+
A problem with the Here-doc syntax given so far is that it must be at the
3020+
left margin of your program, messing up the indentation. Starting in
3021+
Perl v5.26, the tilde C<~> modifier allows you to indent your here-docs
3022+
to make the code more readable.
29573023

29583024
if ($some_var) {
29593025
print <<~EOF;
@@ -2989,91 +3055,82 @@ delimiter) will be preserved:
29893055
This text is indented with two tabs
29903056
EOF
29913057

2992-
Finally, the modifier may be used with all of the forms
2993-
mentioned above:
3058+
=back
29943059

2995-
<<~\EOF;
2996-
<<~'EOF'
2997-
<<~"EOF"
2998-
<<~`EOF`
3060+
=head4 Quoting the delimiter
29993061

3000-
And whitespace may be used between the C<~> and quoted delimiters:
3062+
As mentioned above, the terminating string may be quoted. There are
3063+
three types of quoting possible. The type used determines the treatment
3064+
of the text.
30013065

3002-
<<~ 'EOF'; # ... "EOF", `EOF`
3066+
=over 4
30033067

3004-
=back
3068+
=item Double Quotes
30053069

3006-
It is possible to stack multiple here-docs in a row:
3070+
Double quotes surrounding the terminating word or string behave as if
3071+
no quotes were there, namely the text will be interpolated using exactly
3072+
the same rules as normal double quoted strings, as in all the examples
3073+
above. So
30073074

3008-
print <<"foo", <<"bar"; # you can stack them
3009-
I said foo.
3010-
foo
3011-
I said bar.
3012-
bar
3075+
my $person = 'John';
30133076

3014-
myfunc(<< "THIS", 23, <<'THAT');
3015-
Here's a line
3016-
or two.
3017-
THIS
3018-
and here's another.
3019-
THAT
3077+
print uc << "EOT";
3078+
Hello, $person!
3079+
And the text goes on.
3080+
EOT
30203081

3021-
Just don't forget that you have to put a semicolon on the end
3022-
to finish the statement, as Perl doesn't know you're not going to
3023-
try to do this:
3082+
yields:
30243083

3025-
print <<ABC
3026-
179231
3027-
ABC
3028-
+ 20;
3084+
HELLO, JOHN!
3085+
AND THE TEXT GOES ON.
30293086

3030-
If you want to remove the line terminator from your here-docs,
3031-
use C<chomp()>.
3087+
which is the same result as without quotes.
30323088

3033-
chomp($string = <<'END');
3034-
This is a string.
3035-
END
3089+
=item Single Quotes
30363090

3037-
If you want your here-docs to be indented with the rest of the code,
3038-
use the C<<< <<~FOO >>> construct described under L</Indented Here-docs>:
3091+
If instead, single quotes are used, the text is treated literally, with
3092+
no interpolation of its content.
30393093

3040-
$quote = <<~'FINIS';
3041-
The Road goes ever on and on,
3042-
down from the door where it began.
3043-
FINIS
3094+
my $person = 'John';
3095+
print uc <<'EOT';
3096+
Hello, $person!
3097+
And the text goes on.
3098+
EOT
30443099

3045-
If you use a here-doc within a delimited construct, such as in C<s///eg>,
3046-
the quoted material must still come on the line following the
3047-
C<<< <<FOO >>> marker, which means it may be inside the delimited
3048-
construct:
3100+
HELLO, $PERSON!
3101+
AND THE TEXT GOES ON.
30493102

3050-
s/this/<<E . 'that'
3051-
the other
3052-
E
3053-
. 'more '/eg;
3103+
The difference between a single-quoted here-doc and a single-quoted
3104+
string is that backslashes have no special meaning in a here-doc, with
3105+
C<\\> being treated as two backslashes and not one as they would in
3106+
every other quoting construct.
30543107

3055-
It works this way as of Perl 5.18. Historically, it was inconsistent, and
3056-
you would have to write
3108+
Just as in the shell, a backslashed bareword following the C<<< << >>>
3109+
means the same thing as a single-quoted string does:
30573110

3058-
s/this/<<E . 'that'
3059-
. 'more '/eg;
3060-
the other
3061-
E
3111+
$cost = <<'VISTA'; # hasta la ...
3112+
That'll be $10 please, ma'am.
3113+
VISTA
30623114

3063-
outside of string evals.
3115+
$cost = <<\VISTA; # Same thing!
3116+
That'll be $10 please, ma'am.
3117+
VISTA
30643118

3065-
Additionally, quoting rules for the end-of-string identifier are
3066-
unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
3067-
supported in place of C<''> and C<"">, and the only interpolation is for
3068-
backslashing the quoting character:
3119+
These two forms are the only ways of quoting in Perl where there is no
3120+
need to worry about escaping content, something that code generators can
3121+
and do make good use of.
30693122

3070-
print << "abc\"def";
3071-
testing...
3072-
abc"def
3123+
=item Backticks
30733124

3074-
Finally, quoted strings cannot span multiple lines. The general rule is
3075-
that the identifier must be a string literal. Stick with that, and you
3076-
should be safe.
3125+
Finally, if instead backticks are used to quote the terminating string,
3126+
the content of the here doc is treated just as it would be if it were a
3127+
string embedded in backticks. Thus the content is interpolated as
3128+
though it were double quoted and then executed via the shell, with the
3129+
results of the execution returned.
3130+
3131+
print << `EOC`; # execute command and get results
3132+
echo hi there
3133+
EOC
30773134

30783135
=back
30793136

@@ -3892,6 +3949,10 @@ only to prevent breaking any pre-existing links to it from outside.
38923949

38933950
This section has been replaced by L</Simpler Quote-Like Operators>
38943951

3952+
=head2 Indented Here-docs
3953+
3954+
This section has been merged into by L</Here-docs>
3955+
38953956
=head1 APPENDIX
38963957

38973958
=head2 List of Extra Paired Delimiters

0 commit comments

Comments
 (0)