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 thetr 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
...
<
command2 <
...
<
command3 <
...
<
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 thetextConnection 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