Sometimes large chunks of text need to be printed but it would be inconvenient to print them line by line, or to add line continuation characters (\) at the end of every line. Larger, multi-line texts can be printed in Perl as so-called HERE documents. A HERE document begins and ends with a name token and can span more than a single line. Everything in-between the tokens is considered as one text line by Perl.
The following code example prints an HTML page. The name token used is END. Perl treats everything between print <<END; and the following END as one text line.
#!/usr/local/bin/perl # END is a name token indicating the start and end # of the HERE document # variable interpolation in HERE documents is possible as long # as the starting token is NOT enclosed in single quotation marks $text = "This is an HTML page printed as a HERE document."; print <<END; Content-type: text/html <html> <head> <title> Perl HERE documents</title> </head> <body> <p>$text</p> <!-- variable interpolation --> </body> </html> END # the ending token MUST be the only item on a line # and not be at the end of the file # NOTE: 'Content-type: text/html' (followed by TWO newline # characters is an HTTP header; if it is included in a HERE # document to initiate an HTML page, it must be the first # line in the document; otherwise, a server error may occur
Execute the script with the HERE document.
Note that variable interpolation is enabled, and $text will be expanded to the string the variable contains. If the starting token were enclosed in single quotation marks, print <<'END';, variable interpolation would be disabled.
require
HERE documents also may be imported into and executed by other scripts. Perl provides a function, require, that--when given a file name as an argument--will execute any Perl statements found in that file.
The following script imports the previous example and executes it. The path to the executable HERE document is assigned to a variable. To actually execute it, require is called with the variable as a parameter.
#!/usr/local/bin/perl # a Perl HERE document can also be imported # by other scripts $doc_import = "./perl_here_doc_test.pl"; # the keyword 'require' executes every Perl command # in $doc_import require $doc_import;
The output is exactly the same as in the first example, but the execution is initiated from an external script.
A great advantage of HERE documents is that they allow variable interpolation. Variables can be assigned outside of the files in which the are actually used. If an external script that 'requires' a HERE document includes a variable that exists in the HERE document, normal variable interpolation will take place. If the 'requiring' script does not assign a value, Perl will ignore the variable in the HERE document but continue execution of the script.
The following script is the same as the first example, except that it does not assign a value to $text.
#!/usr/local/bin/perl # an external script that will 'require' this script will # assign a string value to variable $text print <<END; Content-type: text/html <html> <head> <title> Perl HERE documents</title> </head> <body> <p>$text</p> <!-- variable interpolation --> </body> </html> END # the ending token MUST be the only item on a line and # may not be at the end of the file; it MUST be followed # at least by a newline character
The following script imports the HERE document, assigns a value to $text, and executes it with require.
#!/usr/local/bin/perl $doc_import = "./perl_here_doc_test_2.pl"; $text = "This variable was assigned a value in an external script."; # the keyword 'require' executes every Perl command # in $doc_import require $doc_import;