Bash Here Documents

What is a Here Document?

Today, I want to introduce a less known feature to you: Bash Here Documents
They can be used to specify text blocks, while keeping line breaks, white spaces and indentations intact.
Another use case, is to pass a list of commands or lines to interactive commands.

The typical syntax is the following:

COMMAND <<HereDocString
  ..
  ..
  ..
HereDocString

The heredoc is introduced by “<<” followed by a user-definable string. It is common to use “EOF”, but feel free to choose anything you like.
This even lets you use Bash Here Documents inside each other, when you use different strings to start/end them.
IMPORTANT: The string to end the heredoc, MUST NOT have any indentation or white spaces in front of it, but must be the very first word of the line.
It is possible to indent any other line, however.
If you want to use indentation to format your commands, but do not want to include them in the commands itself, add a hyphen (-) in-between the “<<” and the string like so “<<-EOF”.
That is enough theory for now, but what are some actual use cases?

Examples and Use Cases

I want to show you two cases, where I found them to be an excellent option:
To print formatted output:
For one of my shell scripts, I wanted to output an extended usage description including multiple lines and tabs.
Therefore it was really convenient to simply style the output inline, without using escape characters for breaks and new lines.
Here is the example:

function f_usage()
{
cat <<EOF
Usage: $0 [options]
 -f | --file Specify the path to the SAP Note File
 E.g. "ASE_note_1581695"
 -s | --SID Specify the SID of the SAP System
 E.g. "SID"
 -u | --user Specify the SQL_USER
 E.g. "sqluser"
 -p | --pass Sepcify the SQL_PASS
 E.g. "sqlpass"
 -o | --owner Specify the ASE Software Owner
 E.g. "syb<SID>"
 -h | --help Display this help text
EOF
}

I use the heredocs multiple times in this shell script, for example for passing SQL Commands to a Sybase database.
Unlike other database tools, like Oracle’s SQL *Plus, Sybase does not allow to pass commands directly (for example using a flag)
Therefore I have to establish the connection, and then pass the commands using the Here Document, like so:

function f_backup_config()
 {
 echo "[Functio]n: f_backup_config()"
 #--------Begin SQL Command-----------#
 su - $DB_USER -c "isql -U $SQL_USER -P $SQL_PASS -S $SID -w 5000 <<EOF
 sp_configure 'configuration file', 0, 'write', '$DIR/$SID.cfg.$(date +%F_%R)'
 go
 EOF"
 #----------End SQL Command-----------#
 read -n 1 -s -p "Press any key to continue..."
 }

The Linux Documentation Project did a nice writeup about this topic as well, so check it out here: Here Docs
I hope you learned something new and can incorporate that into your own scripts.
Feel free to share this post with your colleagues and leave a comment below if you have any questions or comments!

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.