@@ -2875,85 +2875,151 @@ must use an C<eval()>:
2875
2875
2876
2876
eval "tr/$oldlist/$newlist/, 1" or die $@;
2877
2877
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> >>
2880
2888
2881
2889
A line-oriented form of quoting is based on the shell "here-document"
2882
2890
syntax. Following a C<< << >> you specify a string to terminate
2883
2891
the quoted material, and all lines following the current line down to
2884
2892
the terminating string are the value of the item.
2885
2893
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
2888
2895
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
2895
2901
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,
2898
2906
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.
2900
2909
2901
- =item Double Quotes
2910
+ my $person = 'John';
2902
2911
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
2905
2916
2906
- print <<EOF;
2907
- The price is $Price.
2908
- EOF
2917
+ This yields:
2909
2918
2910
- print << "EOF"; # same as above
2911
- The price is $Price.
2912
- EOF
2919
+ HELLO, JOHN!
2920
+ AND THE TEXT GOES ON.
2913
2921
2922
+ The parentheses in the C<uc> function call don't have to be omitted:
2914
2923
2915
- =item Single Quotes
2924
+ print uc(<<EOT);
2925
+ Hello, $person!
2926
+ And the text goes on.
2927
+ EOT
2916
2928
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.
2922
2931
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:
2925
2933
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
2929
2938
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
2933
2942
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:
2937
2944
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
2939
2951
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
2944
2955
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,
2948
2958
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!
2950
2965
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
2952
3011
2953
- =item Indented Here-docs
3012
+ s/this/<<E . 'that'
3013
+ . 'more '/eg;
3014
+ the other
3015
+ E
3016
+
3017
+ outside of string evals.
2954
3018
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.
2957
3023
2958
3024
if ($some_var) {
2959
3025
print <<~EOF;
@@ -2989,91 +3055,82 @@ delimiter) will be preserved:
2989
3055
This text is indented with two tabs
2990
3056
EOF
2991
3057
2992
- Finally, the modifier may be used with all of the forms
2993
- mentioned above:
3058
+ =back
2994
3059
2995
- <<~\EOF;
2996
- <<~'EOF'
2997
- <<~"EOF"
2998
- <<~`EOF`
3060
+ =head4 Quoting the delimiter
2999
3061
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.
3001
3065
3002
- <<~ 'EOF'; # ... "EOF", `EOF`
3066
+ =over 4
3003
3067
3004
- =back
3068
+ =item Double Quotes
3005
3069
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
3007
3074
3008
- print <<"foo", <<"bar"; # you can stack them
3009
- I said foo.
3010
- foo
3011
- I said bar.
3012
- bar
3075
+ my $person = 'John';
3013
3076
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
3020
3081
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:
3024
3083
3025
- print <<ABC
3026
- 179231
3027
- ABC
3028
- + 20;
3084
+ HELLO, JOHN!
3085
+ AND THE TEXT GOES ON.
3029
3086
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.
3032
3088
3033
- chomp($string = <<'END');
3034
- This is a string.
3035
- END
3089
+ =item Single Quotes
3036
3090
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.
3039
3093
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
3044
3099
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.
3049
3102
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.
3054
3107
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:
3057
3110
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
3062
3114
3063
- outside of string evals.
3115
+ $cost = <<\VISTA; # Same thing!
3116
+ That'll be $10 please, ma'am.
3117
+ VISTA
3064
3118
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.
3069
3122
3070
- print << "abc\"def";
3071
- testing...
3072
- abc"def
3123
+ =item Backticks
3073
3124
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
3077
3134
3078
3135
=back
3079
3136
@@ -3892,6 +3949,10 @@ only to prevent breaking any pre-existing links to it from outside.
3892
3949
3893
3950
This section has been replaced by L</Simpler Quote-Like Operators>
3894
3951
3952
+ =head2 Indented Here-docs
3953
+
3954
+ This section has been merged into by L</Here-docs>
3955
+
3895
3956
=head1 APPENDIX
3896
3957
3897
3958
=head2 List of Extra Paired Delimiters
0 commit comments