Christoph: Created page with "In computing, a '''here document''' ('''here-document''', '''here-text''', '''heredoc''', '''hereis''', '''here-string''', or '''here-script''') is a file literal or input str..."

2020-06-29T00:46:00Z

Created page with "In computing, a '''here document''' ('''here-document''', '''here-text''', '''heredoc''', '''hereis''', '''here-string''', or '''here-script''') is a file literal or input str..."

New page

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.

==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 (Unix)|<code>tr</code>]] command (transliterating lower to upper-case) using a here document. This could be in a shell file or entered interactively at a prompt.

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

<code>END_TEXT</code> 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: <code><<END_TEXT</code> or <code><< END_TEXT</code> both work equally well.

By default, the behaviour is largely identical to the contents of double quotes: variable names are replaced by their values, commands within backticks are evaluated, etc.

<pre>
$ cat << EOF
> \$ Working dir "$PWD" `pwd`
> EOF
$ Working dir "/home/user" /home/user
</pre>
This can be disabled by quoting any part of the label, which is then ended by the unquoted value. "Quoting" includes escaping, so if <code>\EOF</code> is used, this is quoted, so variable interpolation does not occur, and it ends with <code>EOF</code>, while if <code>\\EOF</code> is used, this is quoted and ends with <code>\EOF</code>. This perhaps surprising behaviour is however easily implemented in a shell, by the tokenizer simply recording a token was quoted (during the evaluation phase of lexical analysis), without needing to preserve the original, quoted value.<br/>
One application is to use <code>\'</code> as the starting delimiter and thus <code>'</code> as the ending delimiter, which is similar to a multiline string literal but stripping starting and ending linebreaks. The behaviour is essentially identical to that if the contents were enclosed in single quotes. Thus for example by setting it in single quotes:

<pre>
$ cat << 'EOF'
> \$ Working dir "$PWD" `pwd`
> EOF
\$ Working dir "$PWD" `pwd`
</pre>
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]] (see below), where behaviour parallels the corresponding string quoting.

Appending a minus sign to the << (i.e. <code><<-</code>) has the effect that leading tabs are ignored. (Not in csh or tcsh.) This allows indenting here documents in shell scripts (primarily for alignment with existing indentation) without changing their value. (Note that while tabs can typically be entered in editors, at the command line they are typically entered by <code>Ctrl-V + Tab</code> instead, due to tab completion, and in the example, they are actual tabs, so the example can be copy and pasted.)

A script containing:

<pre>
LANG=C tr a-z A-Z <<- END_TEXT
Here doc with <<-
A single space character (i.e. 0x20 ) is at the beginnning 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 (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 and
echo the tr command continued processing.
</pre>

produces:
<pre>
HERE 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
The intended end was before this line
and these were not processed by tr
+++++++++++++++
HERE DOC WITH <<
A SINGLE SPACE CHARACTER (I.E. 0X20 ) IS AT THE BEGINNNING 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.
</pre>

Another use is to output to a file:
<pre>
cat << EOF > ~/testFile001
> 3 spaces precede this text.
> A single tab character is at the beginning of this line.
>Nothing precedes this text
EOF
</pre>

====Here strings====
A '''here string''' (available in bash, ksh, or zsh) is syntactically similar, consisting of <code><<<</code>, 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:
<pre>
$ LANG=C tr a-z A-Z <<< one
ONE
</pre>
In case of a string with spaces, it must be quoted:
<pre>
$ LANG=C tr a-z A-Z <<< 'one two three'
ONE TWO THREE
</pre>
This could also be written as:
<pre>
$ foo='one two three'
$ LANG=C tr a-z A-Z <<< "$foo"
ONE TWO THREE
</pre>
Multiline strings are acceptable, yielding:
<pre>
$ LANG=C tr a-z A-Z <<< 'one
> two three'
ONE
TWO THREE
</pre>
Note that leading and trailing newlines, if present, are included:
<pre>
$ LANG=C tr a-z A-Z <<< '
> one
> two three
> '

ONE
TWO THREE

$
</pre>
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:
<pre>
$ bc <<< 2^10
1024

#~OR~
$ for i in $(seq 1 10); do bc <<< 2^$i; done
2
4
8
16
32
64
128
256
512
1024
</pre>

Note that here string behavior can also be accomplished (reversing the order) via piping and the [[echo (command)|<code>echo</code>]] command, as in:
<pre>
$ echo 'one two three' | LANG=C tr a-z A-Z
ONE TWO THREE
</pre>
however here strings are particularly useful when the last command needs to run in the current process, as is the case with the <code>read</code> builtin:
<pre>
$ echo 'one two three' | read -r a b c
$ echo "$a $b $c"
</pre>
yields nothing, while
<pre>
$ read -r a b c <<< 'one two three'
$ echo "$a $b $c"
one two three
</pre>
This happens because in the previous example piping causes <code>read</code> to run in a subprocess, and as such can not affect the environment of the parent process.

[[Category:Linux Command Line Tools]]

Here document - Revision history

Christoph: Created page with "In computing, a '''here document''' ('''here-document''', '''here-text''', '''heredoc''', '''hereis''', '''here-string''', or '''here-script''') is a file literal or input str..."