Perl logo

Perl Refreshments ⌘

Treat - Here Documents

Here documents are popular in several other languages such as Python, Ruby, PHP, and even Linux or Unix shells.

Technically they are file or input stream literals. The term also refers to a multiline string literal, which is the one we are talking about here.

If you have a long string such as a paragraph, or even a whole page of text that you need or want to make available as a string in your program, using a 'here document' is the best way to do that.

For example, I have 3 paragraphs that I need to include in some text I'm creating, but I need to add them several times throughout my text. How would I do that?

Here's the text:

Qui pariatur fugit dolorem provident. Repudiandae eum ullam harum.
Voluptas enim soluta voluptatem cum. Deleniti et est consequatur
facere doloremque molestiae. Quia quo velit ex ut consequatur corrupti
numquam reiciendis.

Eveniet a voluptatem tenetur dolore distinctio. Aut accusantium enim
esse voluptatem. Aspernatur quisquam animi illum.

Aperiam quis reprehenderit dolore eius. Quod deleniti et ex sit nostrum
sequi ut laboriosam. Modi voluptatem est saepe.

For the sake of simplicity I used a Perl module to create that (Text::Lorem) but you will probably have something more meaningful you want to use. (I don't speak Lorem)

In any case, we have 3 paragraphs we want to include several times. So how do we do that?

I write a lot of code that will become part of a web site, and a lot of that code requires some Perl activity. Here is how I would typically write an HTML page in Perl ...

#! /usr/bin/perl -w
use strict;
use warnings;

print "Content-type: text/html; charset=utf-8\n\n";

<!-- We MUST print a content-type first, ending with 2 blank lines. -->
<!-- Since we are writing a web page, the content-type is 'text/html'. -->

print <<EndHTML; <!-- magick starts here -->

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<title>A Perl 'Here' Document</title>
<link rel="stylesheet" type="text/css" media="screen" title="Custom Settings" href="$CSS" >
</head>
<body>
<h1>This Here is a 'here document'</h1>
</body>
</html>
EndHTML <!-- the magick ends here -->

Note the 2 'magick' lines. They wrap a block of text in a special quote operator.

The end line MUST end with a semi-colon (remember we are executing a print command).

It MUST also begin at the left margin with NO spaces or tabs.


The tokens used to wrap your block of text can be almost anything, but if it contains any spaces or tabs, the token must be quoted. AND the ending token must be indented exactly the same amount.

Of course, you wouldn't write a simple HTML page like this in Perl - you are using Perl because it's needed for some server activity.

Note the line specifying an external style sheet - the href is '$CSS' which looks surprisingly like a Perl variable. And you would be right. Prior to creating the here document, I've initialized several Perl variables, which are rendered perfectly in the block.

These blocks of code can be used any number of times in your script. For example, after the <h1> line I may want to connect to a database and display some information.

In the previous code I might do the following:

#! /usr/bin/perl -w
use strict;
use warnings;

print "Content-type: text/html; charset=utf-8\n\n";
print <<EndHTML;

<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<title>A Perl 'Here' Document</title>
<link rel="stylesheet" type="text/css" media="screen" title="Custom Settings" href="$CSS" >
</head>
<body>
<h1>This Here is a 'here document'</h1>
EndHTML

DBconnect();
$sth=$dbh->prepare(qq{select keyword from keywords group by keyword order by lower(keyword)});
$sth->execute();
while (@records = $sth->fetchrow_array())
{
     next if ($records[0] eq "");
     print qq{$records[0]</br>};
}
$sth->finish();

print <<EndHTML;
<p>That was a list of keywords in my KB database</p>
</body>
</html>
EndHTML

Comments & Documentation

-30-