Tweet

HERE documents

Introduction

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.

Quoting conventions.

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

The terminating string

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 ....

Assignment

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

See Also

     perldoc -q "HERE documents"
     perldoc perlop (see the <<EOF section).
     Perl for Newbies - Lecture 4
Revision: 1.2 [Top]