In computing, a here document (here-document, here-text, heredoc, hereis, here-string or here-script) 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 (including indentation) in the text.
Here documents originate in the Unix shell, and are found in the Bourne shell (sh), C shell (csh),[1] tcsh (tcsh), KornShell (ksh), Bourne Again Shell (bash), and Z shell (zsh), among others. Here document-style string literals are found in various high-level languages, notably the Perl programming language (syntax inspired by Unix shell) 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 (ES6). 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.
The most common syntax for here documents, originating in Unix shells, is << followed by a delimiting identifier (often the word EOF or END[2]), 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 (standard input) 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.
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.
Here documents are available in many Unix shells.[3] In the following example, text is passed to the tr command (transliterating lower to upper-case) using a here document. This could be in a shell file, or entered interactively at a prompt.
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.
In POSIX shell but not csh/tcsh, appending a minus sign to the (i.e.) has the effect that leading tabs are ignored.[5] This allows indenting here documents in shell scripts (primarily for alignment with existing indentation) without changing their value:
A script containing:
echo The intended end was before this line echo and these were not processed by trecho +++++++++++++++
LANG=C tr a-z A-Z << END_TEXTHere doc with << A single space character (i.e. 0x20) 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 andecho the tr command continued processing.
produces:
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 ANDECHO THE TR COMMAND CONTINUED PROCESSING.
Another use is to output to a file:
A here string (available in bash, ksh, or zsh) is syntactically similar, consisting of, and effects input redirection from a word (a sequence treated as a unit by the shell, in this context generally a string literal). In this case the usual shell syntax is used for the word (“here string syntax”), 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:
ONETWO 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 (programming language)|bc]]:[[echo (command)|echo]] command, as in:[[read (Unix)|read]] builtin:read to run in a subprocess, and as such cannot affect the environment of the parent process.
In Microsoft NMAKE, here documents are referred to as inline files. Inline files are referenced as target1: dependent1 command1 < target2: dependent2 command2 < target3: dependent3 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 the Perl[6] and Ruby[7] have a form of file literal, which can be considered a form of data segment. In these languages, including the line As further explained in Data URI scheme, all major web browsers understand URIs that start with data: as here document. The term "here document" or "here string" is also used for multiline string literals in various programming languages, notably Perl (syntax influenced by Unix shell), and languages influenced by Perl, notably PHP and Ruby. The shell-style In Perl there are several different ways to invoke here docs.[8] The delimiters around the tag have the same effect within the here doc as they would in a regular string literal: For example, using double quotes around the tag allows variables to be interpolated, but using single quotes doesn't, and using the tag without either behaves like double quotes. Using backticks as the delimiters around the tag runs the contents of the heredoc as a shell script. It is necessary to make sure that the end tag is at the beginning of the line or the tag will not be recognized by the interpreter. Note that the here doc does not start at the tag—but rather starts on the next line. So the statement containing the tag continues on after the tag. Here is an example with double quotes: print <<"END"; Dear $recipient, I wish you to leave Sunnydale and never return. Not Quite Love,$sender END<< or <<pathname: the first notation creates a temporary file, the second notation creates (or overwrites) the file with the specified pathname.An inline file is terminated with << on a line by itself, optionally followed by the (case-insensitive) keyword KEEP or NOKEEP to indicate whether the created file should be kept.R
textConnection function. For example, the following turns a data table embedded in the source code into a data-frame variable:Data segment
__DATA__ (Perl) or __END__ (Ruby, old Perl) marks the end of the code segment and the start of the data segment. Only the contents prior to this line are executed, and the contents of the source file after this line are available as a file object: PACKAGE::DATA in Perl (e.g., main::DATA) and DATA in Ruby. As an inline file, these are semantically similar to here documents, though there can be only one per script. However, in these languages the term "here document" instead refers to multiline string literals, as discussed below.Data URI Scheme
Multiline string literals
<< syntax is often retained, despite not being used for input redirection.Perl-influenced
Perl
Output:Here is an example with single quotes:
I wish you to leave Sunnydale and never return.
Not Quite Love,$senderEND
Output:And an example with backticks (may not be portable):
It is possible to start multiple heredocs on the same line:
say("This is the beginning:\nthis is the middle\nAnd now it is over!\n");
The tag itself may contain whitespace, which may allow heredocs to be used without breaking indentation.
Although since Perl version 5.26,[9] heredocs can include indention:
In addition to these strings, Perl also features file literals, namely the contents of the file following __DATA__ (formerly __END__) on a line by itself. This is accessible as the file object PACKAGE::DATA such as main::DATA, and can be viewed as a form of data segment.
In PHP, here documents are referred to as heredocs. In PHP heredocs are not string literals. Heredoc text behaves just like a double-quoted string, but without the double quotes. For example, meaning `$` will be parsed as a variable start, and `$