Perl heredoc
last modified October 20, 2026
A here-document, or heredoc, is a way to write a multi-line string literal
without quoting each line. The text starts after a << marker
and ends at a line that contains only the marker. Heredocs are useful for
templates, usage messages, SQL statements, and embedded configuration.
Interpolating heredoc with double quotes
When the marker is in double quotes, or written bare, the text behaves like a
double-quoted string: variables and expressions inside
@{[ ... ]} are interpolated.
#!/usr/bin/perl
use strict;
use warnings;
use v5.34.0;
my $name = 'Alice';
print <<"END";
Hello, $name!
Interpolation happens here: 2 + 2 = @{[ 2 + 2 ]}
END
The marker END is the terminator. The variable
$name is replaced with its value, and the expression
@{[ 2 + 2 ]} is evaluated and inserted as text. The terminator
line must match exactly, with no leading spaces, and the final newline of the
block is included in the string.
$ perl interpolate.pl Hello, Alice! Interpolation happens here: 2 + 2 = 4
Literal heredoc with single quotes
Quoting the marker with single quotes turns off interpolation, so the text is kept exactly as written. This is the right form for shell snippets, regular expressions, or any text that contains dollar signs meant literally.
#!/usr/bin/perl
use strict;
use warnings;
use v5.34.0;
my $name = 'Alice';
print <<'RAW';
No interpolation: $name and @{[ 2 + 2 ]}
RAW
Neither $name nor the expression is evaluated. The output contains
the characters exactly as they were typed, which makes this form safe for
text that must not be changed.
$ perl literal.pl
No interpolation: $name and @{[ 2 + 2 ]}
Indented heredoc with <<~
Perl 5.26 added the <<~ form, which allows the terminator
to be indented and removes the common leading whitespace from every line of the
body. The indentation of the content is therefore free to match the code
around it, while the output stays flush left.
#!/usr/bin/perl
use strict;
use warnings;
use v5.34.0;
print <<~INDENT;
Indented heredoc keeps
relative indentation
and strips the common prefix
INDENT
The body is indented by four spaces, and the smallest indentation among its lines is four spaces, so exactly that prefix is removed. The line that is indented by six spaces keeps two extra spaces relative to the others. Lines with less indentation than the terminator are an error.
$ perl indented.pl Indented heredoc keeps relative indentation and strips the common prefix
Using a heredoc as a function argument
A heredoc is an ordinary string expression, so it can be passed to a function or stored in a variable. The text begins on the line after the statement, so the rest of the statement continues on the first line.
#!/usr/bin/perl
use strict;
use warnings;
use v5.34.0;
sub show_length {
my ($text) = @_;
my @lines = split /\n/, $text;
say "lines: ", scalar @lines;
say "first: $lines[0]";
}
show_length(<<~TEXT);
alpha
beta
gamma
TEXT
The heredoc is passed directly as the argument to show_length. The
split turns the text into lines, which lets the subroutine count them. The
terminator line closes the string, and the closing parenthesis and semicolon on
the first line still belong to the call.
$ perl argument.pl lines: 3 first: alpha
Best Practices
- Use single quotes for literal text: templates and snippets
that must not be changed should use
<<'END'. - Prefer <<~ for indented code: it keeps the source readable without adding spaces to the output.
- Choose a descriptive terminator: a marker such as
SQLorUSAGEmakes the purpose of the block clear. - Keep terminators unique: the marker must not appear as a line of its own inside the text.
In this article we have covered heredocs in Perl, including interpolating and
literal forms, the indented <<~ form, and passing a heredoc
as an argument.
Source
perlop: Quote and Quote-like Operators
Author
List all Perl tutorials.