Wandering Thoughts: Recent Entries For 2009/10/01

The rules for combining things with Bourne shell 'here documents'

Shell here documents are relatively simple to use on their own, but it's usually head-scratching to combine them with other things (redirections, pipelines, or conditionals). To save me having to do the experimentation and manpage reading the next time, here's the simple version of the rules: here documents always start at the next line.

So you can write any number of other things on the same line as the command with a here document:

cat <<EOF | ssh host ...
foo
EOF

But if you need to continue the whole thing on additional lines, you must write the following commands after the here document:

ssh host ... <<EOF ||
foo
EOF
	echo "ssh failed"

However, 'next line' here means the next line as seen by the Bourne shell after backslash-escaped newlines, so you cannot write the last example with the ssh line ended with a '\' and the '||' at the start of the echo line. (This is a pity, as I think it would be more readable. But frankly, combining here documents and multiple commands this way is never going to be terribly readable.)

Because of this, other redirections can go anywhere on the command line with the here document, as can arguments and so on; 'ssh <<EOF host ... >logfile 2>&1' is perfectly legal. The maximally perverse version of this is:

<<EOF ssh host ... 
foo
EOF

My opinion is 'don't do that'; put the here document redirection last on the line if at all possible, to avoid confusing other people.

Somewhat to my surprise it's possible to specify multiple here documents on the same line. If you do this crazy thing, the shell expects them to be in left to right order, eg:

sed 's/^/a: /' <<EOF && cat <<EF2
foo
EOF
bar
EF2

But, really, don't do this.