Home » Howtos » Syntax » Here document |
If you're tempted to write multi-line output with multiple print()
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";
with this:
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
The 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 "
or '
, you
cannot use the equivalent qq()
and 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
string 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
.
$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 sprintf()
:
$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