Here document


In computing, a here document is a file literal or input stream literal: it is a section of a source code file that is treated as if it were a separate file. The term is also used for a form of multiline string literals that use similar syntax, preserving line breaks and other whitespace in the text.
Here documents originate in the Unix shell, and are found in the Bourne shell since 1979, and most subsequent shells. Here document-style string literals are found in various high-level languages, notably the Perl programming language and languages influenced by [|Perl], such as PHP and Ruby. JavaScript also supports this functionality via template literals, a feature added in its 6th revision. Other high-level languages such as Python, Julia and Tcl have other facilities for multiline strings.
Here documents can be treated either as files or strings. Some shells treat them as a format string literal, allowing variable substitution and command substitution inside the literal.

Overview

The most common syntax for here documents, originating in Unix shells, is << followed by a delimiting identifier, followed, starting on the next line, by the text to be quoted, and then closed by the same delimiting identifier on its own line. This syntax is because here documents are formally stream literals, and the content of the here document is often redirected to stdin of the preceding command or current shell script/executable.
The here document syntax is analogous to the shell syntax for input redirection, which is < followed by the name of the file to be used as input.
Other languages often use substantially similar syntax, but details of syntax and actual functionality can vary significantly. When used simply for string literals, the << does not indicate indirection, but is simply a starting delimiter convention. In some languages, such as Ruby, << is also used for input redirection, thus resulting in << being used twice if one wishes to redirect from a here document string literal.

File literals

Narrowly speaking, here documents are file literals or stream literals. These originate in the Unix shell, though similar facilities are available in some other languages.

Unix shells

Here documents are available in many Unix shells. In the following example, text is passed to the tr command using a here document. This could be in a shell file, or entered interactively at a prompt.

$ LANG=C tr a-z A-Z << END
> one two three
> four five six
> END
ONE TWO THREE
FOUR FIVE SIX

In this case END was used as the delimiting identifier. It specified the start and end of the here document. The redirect and the delimiting identifier do not need to be separated by a space: or both work equally well.
By default, behavior is largely identical to the contents of double quotes: variable names are replaced by their values, commands within backticks are evaluated, etc.

$ cat << EOF
> \$ Working dir "$PWD" `pwd`
> EOF
$ Working dir "/home/user" /home/user

This can be disabled by quoting any part of the label, which is then ended by the unquoted value; the behavior is essentially identical to that if the contents were enclosed in single quotes. Thus for example by setting it in single quotes:

$ cat << 'EOF'
> \$ Working dir "$PWD" `pwd`
> EOF
\$ Working dir "$PWD" `pwd`

Double quotes may also be used, but this is subject to confusion, because expansion does occur in a double-quoted string, but does not occur in a here document with double-quoted delimiter. Single- and double-quoted delimiters are distinguished in some other languages, notably Perl, where behavior parallels the corresponding string quoting.
In POSIX shell but not csh/tcsh, appending a minus sign to the has the effect that leading tabs are ignored. This allows indenting here documents in shell scripts without changing their value:
A script containing:

LANG=C tr a-z A-Z <<- END_TEXT
Here doc with <<-
A single space character is at the beginning of this line
This line begins with a single TAB character i.e 0x09 as does the next line
END_TEXT
echo The intended end was before this line
echo and these were not processed by tr
echo +++++++++++++++
LANG=C tr a-z A-Z << END_TEXT
Here doc with <<
A single space character is at the beginning of this line
This line begins with a single TAB character i.e 0x09 as does the next line
END_TEXT
echo The intended end was before this line,
echo but because the line with the delimiting Identifier began with a TAB it was NOT recognized and
echo the tr command continued processing.

produces:

HERE DOC WITH <<-
A SINGLE SPACE CHARACTER IS AT THE BEGINNING OF THIS LINE
THIS LINE BEGINS WITH A SINGLE TAB CHARACTER I.E 0X09 AS DOES THE NEXT LINE
The intended end was before this line
and these were not processed by tr
+++++++++++++++
HERE DOC WITH <<
A SINGLE SPACE CHARACTER IS AT THE BEGINNING OF THIS LINE
THIS LINE BEGINS WITH A SINGLE TAB CHARACTER I.E 0X09 AS DOES THE NEXT LINE
END_TEXT
ECHO THE INTENDED END WAS BEFORE THIS LINE,
ECHO BUT BECAUSE THE LINE WITH THE DELIMITING IDENTIFIER BEGAN WITH A TAB IT WAS NOT RECOGNIZED AND
ECHO THE TR COMMAND CONTINUED PROCESSING.

Another use is to output to a file:

$ cat << EOF > ~/testFile001
> 3 spaces precede this text.
> A single tab character is at the beginning of this line.
>Nothing precedes this text
EOF

Here strings

A here string is syntactically similar, consisting of, and effects input redirection from a word. In this case the usual shell syntax is used for the word, with the only syntax being the redirection: a here string is an ordinary string used for input redirection, not a special kind of string.
A single word need not be quoted:

$ LANG=C tr a-z A-Z <<< one
ONE

In case of a string with spaces, it must be quoted:

$ LANG=C tr a-z A-Z <<< 'one two three'
ONE TWO THREE

This could also be written as:

$ foo='one two three'
$ LANG=C tr a-z A-Z <<< "$foo"
ONE TWO THREE

Multiline strings are acceptable, yielding:

$ LANG=C tr a-z A-Z <<< 'one
> two three'
ONE
TWO THREE

Note that leading and trailing newlines, if present, are included:

$ LANG=C tr a-z A-Z <<< '
> one
> two three
> '
ONE
TWO THREE

The key difference from here documents is that, in here documents, the delimiters are on separate lines; the leading and trailing newlines are stripped. Unlike here documents, here strings do not use delimiters.
Here strings are particularly useful for commands that often take short input, such as the calculator bc:

$ bc <<< 2^10
1024

Note that here string behavior can also be accomplished via piping and the echo command, as in:

$ echo 'one two three' | LANG=C tr a-z A-Z
ONE TWO THREE

however here strings are particularly useful when the last command needs to run in the current process, as is the case with the read builtin:

$ echo 'one two three' | read -r a b c
$ echo "$a $b $c"

yields nothing, while

$ read -r a b c <<< 'one two three'
$ echo "$a $b $c"
one two three

This happens because in the previous example piping causes read to run in a subprocess, and as such cannot affect the environment of the parent process.

Microsoft NMAKE

In Microsoft NMAKE, here documents are referred to as . Inline files are referenced as << or <<pathname: the first notation creates a temporary file, the second notation creates the file with the specified pathname.
An inline file is terminated with << on a line by itself, optionally followed by the keyword KEEP or NOKEEP to indicate whether the created file should be kept.

target0: dependent0
command0 <<
temporary inline file
...
<<
target1: dependent1
command1 <<
temporary, but preserved inline file
...
<target2: dependent2
command2 <named, but discarded inline file
...
<target3: dependent3
command3 <named inline file
...
<

R

does not have file literals, but provides equivalent functionality by combining string literals with a string-to-file function. R allows arbitrary whitespace, including newlines, in strings. A string then can be turned into a file descriptor using the textConnection function. For example, the following turns a data table embedded in the source code into a data-frame variable:

str <-
"State Population Income Illiteracy Life.Exp Murder HS.Grad Frost
Alabama 3615 3624 2.1 69.05 15.1 41.3 20
Alaska 365 6315 1.5 69.31 11.3 66.7 152
Arizona 2212 4530 1.8 70.55 7.8 58.1 15
Arkansas 2110 3378 1.9 70.66 10.1 39.9 65"
x <- read.table