|Home » Howtos » Syntax » Here document|
If you're tempted to write multi-line output with multiple
statements, because that's what you're used to in some other language,
consider using a HERE-document instead.
Inspired by the here-documents in the Unix command line shells, Perl HERE-documents provide a convenient way to handle the quoting of multi-line values.
So you can replace this:
print "Welcome to the MCG Carpark.\n"; print "\n"; print "There are currently 2,506 parking spaces available.\n"; print "Please drive up to a booth and collect a ticket.\n";
print <<'EOT'; Welcome to the MCG Carpark. There are currently 2,506 parking spaces available. Please drive up to a booth and collect a ticket. EOT
EOT in this example is an arbitrary string that you provide to
indicate the start and end of the text being quoted. The terminating string
must appear on a line by itself.
The usual Perl quoting conventions apply, so if you want to interpolate variables in a here-document, use double quotes around your chosen terminating string:
print <<"EOT"; Welcome to the MCG Carpark. There are currently $available_places parking spaces available. Please drive up to booth and collect a ticket. EOT
Note that whilst you can quote your terminator with
cannot use the equivalent
q() operators. So this
code is invalid:
# This example will fail print <<qq(EOT); Welcome to the MCG Carpark. There are currently $available_places parking spaces available. Please drive up to booth and collect a ticket. EOT
Naturally, all of the text you supply to a here-document is quoted by the starting and ending strings. This means that any indentation you provide becomes part of the text that is used. In this example, each line of the output will contain four leading spaces.
# Let's indent the text to be displayed. The leading spaces will be # preserved in the output. print <<"EOT"; Welcome to the MCG Carpark. CAR PARK FULL. EOT
The terminating string must appear on a line by itself, and it must
have no whitespace before or after it. In this example, the terminating
EOT is preceded by four spaces, so Perl will not find it:
# Let's indent the following lines. This introduces an error print <<"EOT"; Welcome to the MCG Carpark. CAR PARK FULL. EOT
Can't find string terminator "EOT" anywhere before EOF at ....
The here-document mechanism is just a generalized means of quoting text, so you can just as easily use it in an assignment:
my $message = <<"EOT"; Welcome to the MCG Carpark. CAR PARK FULL. EOT print $message;
And don't let the samples you've seen so far stop from considering the full range of possibilities. The terminating tag doesn't have to appear at the end of a statement.
Here is an example from
CPAN.pm that conditionally assigns some text to
$msg = <<EOF unless $configpm =~ /MyConfig/; # This is CPAN.pm's systemwide configuration file. This file provides # defaults for users, and the values can be changed in a per-user # configuration file. The user-config file is being looked for as # ~/.cpan/CPAN/MyConfig.pm. EOF
And this example from Module::Build::PPMMaker uses a here-document to
construct the format string for
$ppd .= sprintf(<<'EOF', $perl_version, $^O, $self->_varchname($build->config) ); <PERLCORE VERSION="%s" /> <OS NAME="%s" /> <ARCHITECTURE NAME="%s" /> EOF
perldoc -q "HERE documents" perldoc perlop (see the <<EOF section). Perl for Newbies - Lecture 4