File: here-docs.html

package info (click to toggle)
abs-guide 10-4
links: PTS, VCS
area: main
in suites: bookworm, bullseye, forky, sid, trixie
size: 6,952 kB
sloc: sh: 14,129; makefile: 81
file content (1983 lines) | stat: -rw-r--r-- 40,616 bytes
parent folder | download | duplicates (3)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML
><HEAD
><TITLE
>Here Documents</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="Advanced Bash-Scripting Guide"
HREF="index.html"><LINK
REL="UP"
TITLE="Advanced Topics"
HREF="part5.html"><LINK
REL="PREVIOUS"
TITLE="Globbing"
HREF="globbingref.html"><LINK
REL="NEXT"
TITLE="I/O Redirection"
HREF="io-redirection.html"><META
HTTP-EQUIV="Content-Style-Type"
CONTENT="text/css"><LINK
REL="stylesheet"
HREF="common/kde-common.css"
TYPE="text/css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=iso-8859-1"><META
HTTP-EQUIV="Content-Language"
CONTENT="en"><LINK
REL="stylesheet"
HREF="common/kde-localised.css"
TYPE="text/css"
TITLE="KDE-English"><LINK
REL="stylesheet"
HREF="common/kde-default.css"
TYPE="text/css"
TITLE="KDE-Default"></HEAD
><BODY
CLASS="CHAPTER"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#AA0000"
VLINK="#AA0055"
ALINK="#AA0000"
STYLE="font-family: sans-serif;"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Advanced Bash-Scripting Guide: An in-depth exploration of the art of shell scripting</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="globbingref.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="io-redirection.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="CHAPTER"
><H1
><A
NAME="HERE-DOCS"
></A
>Chapter 19. Here Documents</H1
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="EPIGRAPH"
><TR
><TD
WIDTH="45%"
>&nbsp;</TD
><TD
WIDTH="45%"
ALIGN="LEFT"
VALIGN="TOP"
><I
><P
><I
>Here and now, boys.</I
></P
><P
><I
>--Aldous Huxley, <I
CLASS="FIRSTTERM"
>Island</I
></I
></P
></I
></TD
></TR
></TABLE
><P
><A
NAME="HEREDOCREF"
></A
></P
><P
>A <I
CLASS="FIRSTTERM"
>here document</I
> is a special-purpose
	code block. It uses a form of <A
HREF="io-redirection.html#IOREDIRREF"
>I/O
	redirection</A
> to feed a command list to
	an interactive program or a command, such as <A
HREF="communications.html#FTPREF"
>ftp</A
>, <A
HREF="external.html#CATREF"
>cat</A
>,
	or the <I
CLASS="FIRSTTERM"
>ex</I
> text editor.</P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;COMMAND &#60;&#60;InputComesFromHERE
   2&nbsp;...
   3&nbsp;...
   4&nbsp;...
   5&nbsp;InputComesFromHERE</PRE
></TD
></TR
></TABLE
></P
><P
><A
NAME="LIMITSTRINGREF"
></A
></P
><P
>A <I
CLASS="FIRSTTERM"
>limit string</I
> delineates (frames)
	the command list.  The special symbol <SPAN
CLASS="TOKEN"
>&#60;&#60;</SPAN
> precedes
	the limit string.  This has the effect of redirecting the output
	of a command block into the <TT
CLASS="FILENAME"
>stdin</TT
> of the program
	or command. It is similar to <TT
CLASS="USERINPUT"
><B
>interactive-program &#60;
	command-file</B
></TT
>, where <TT
CLASS="FILENAME"
>command-file</TT
>
	contains

	  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;command #1
   2&nbsp;command #2
   3&nbsp;...</PRE
></TD
></TR
></TABLE
></P
><P
>The <I
CLASS="FIRSTTERM"
>here document</I
> equivalent looks
        like this:

      <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;interactive-program &#60;&#60;LimitString
   2&nbsp;command #1
   3&nbsp;command #2
   4&nbsp;...
   5&nbsp;LimitString</PRE
></TD
></TR
></TABLE
></P
><P
>Choose a <I
CLASS="FIRSTTERM"
>limit string</I
> sufficiently
	unusual that it will not occur anywhere in the command list and
	confuse matters.</P
><P
>Note that <I
CLASS="FIRSTTERM"
>here documents</I
> may sometimes
	be used to good effect with non-interactive utilities and commands,
	such as, for example, <A
HREF="system.html#WALLREF"
>wall</A
>.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX70"
></A
><P
><B
>Example 19-1. <I
CLASS="FIRSTTERM"
>broadcast</I
>: Sends message to everyone
	logged in</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;wall &#60;&#60;zzz23EndOfMessagezzz23
   4&nbsp;E-mail your noontime orders for pizza to the system administrator.
   5&nbsp;    (Add an extra dollar for anchovy or mushroom topping.)
   6&nbsp;# Additional message text goes here.
   7&nbsp;# Note: 'wall' prints comment lines.
   8&nbsp;zzz23EndOfMessagezzz23
   9&nbsp;
  10&nbsp;# Could have been done more efficiently by
  11&nbsp;#         wall &#60;message-file
  12&nbsp;#  However, embedding the message template in a script
  13&nbsp;#+ is a quick-and-dirty one-off solution.
  14&nbsp;
  15&nbsp;exit</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="VIHERE"
></A
></P
><P
>Even such unlikely candidates as the <I
CLASS="FIRSTTERM"
>vi</I
>
        text editor lend themselves to <I
CLASS="FIRSTTERM"
>here
        documents</I
>.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX69"
></A
><P
><B
>Example 19-2. <I
CLASS="FIRSTTERM"
>dummyfile</I
>: Creates a 2-line dummy
	file</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;# Noninteractive use of 'vi' to edit a file.
   4&nbsp;# Emulates 'sed'.
   5&nbsp;
   6&nbsp;E_BADARGS=85
   7&nbsp;
   8&nbsp;if [ -z "$1" ]
   9&nbsp;then
  10&nbsp;  echo "Usage: `basename $0` filename"
  11&nbsp;  exit $E_BADARGS
  12&nbsp;fi
  13&nbsp;
  14&nbsp;TARGETFILE=$1
  15&nbsp;
  16&nbsp;# Insert 2 lines in file, then save.
  17&nbsp;#--------Begin here document-----------#
  18&nbsp;vi $TARGETFILE &#60;&#60;x23LimitStringx23
  19&nbsp;i
  20&nbsp;This is line 1 of the example file.
  21&nbsp;This is line 2 of the example file.
  22&nbsp;^[
  23&nbsp;ZZ
  24&nbsp;x23LimitStringx23
  25&nbsp;#----------End here document-----------#
  26&nbsp;
  27&nbsp;#  Note that ^[ above is a literal escape
  28&nbsp;#+ typed by Control-V &#60;Esc&#62;.
  29&nbsp;
  30&nbsp;#  Bram Moolenaar points out that this may not work with 'vim'
  31&nbsp;#+ because of possible problems with terminal interaction.
  32&nbsp;
  33&nbsp;exit</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>        The above script could just as effectively have been implemented with
	<B
CLASS="COMMAND"
>ex</B
>, rather than
	<B
CLASS="COMMAND"
>vi</B
>. <A
NAME="EXSCRIPTREF"
></A
><I
CLASS="FIRSTTERM"
>Here
	documents</I
> containing a list of <B
CLASS="COMMAND"
>ex</B
>
	commands are common enough to form their own category, known as
	<I
CLASS="FIRSTTERM"
>ex scripts</I
>.

	  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;#  Replace all instances of "Smith" with "Jones"
   3&nbsp;#+ in files with a ".txt" filename suffix. 
   4&nbsp;
   5&nbsp;ORIGINAL=Smith
   6&nbsp;REPLACEMENT=Jones
   7&nbsp;
   8&nbsp;for word in $(fgrep -l $ORIGINAL *.txt)
   9&nbsp;do
  10&nbsp;  # -------------------------------------
  11&nbsp;  ex $word &#60;&#60;EOF
  12&nbsp;  :%s/$ORIGINAL/$REPLACEMENT/g
  13&nbsp;  :wq
  14&nbsp;EOF
  15&nbsp;  # :%s is the "ex" substitution command.
  16&nbsp;  # :wq is write-and-quit.
  17&nbsp;  # -------------------------------------
  18&nbsp;done</PRE
></TD
></TR
></TABLE
>
	</P
><P
><A
NAME="CATSCRIPTREF"
></A
></P
><P
>Analogous to <SPAN
CLASS="QUOTE"
>"ex scripts"</SPAN
> are <I
CLASS="FIRSTTERM"
>cat
        scripts</I
>.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX71"
></A
><P
><B
>Example 19-3. Multi-line message using <I
CLASS="FIRSTTERM"
>cat</I
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;#  'echo' is fine for printing single line messages,
   4&nbsp;#+  but somewhat problematic for for message blocks.
   5&nbsp;#   A 'cat' here document overcomes this limitation.
   6&nbsp;
   7&nbsp;cat &#60;&#60;End-of-message
   8&nbsp;-------------------------------------
   9&nbsp;This is line 1 of the message.
  10&nbsp;This is line 2 of the message.
  11&nbsp;This is line 3 of the message.
  12&nbsp;This is line 4 of the message.
  13&nbsp;This is the last line of the message.
  14&nbsp;-------------------------------------
  15&nbsp;End-of-message
  16&nbsp;
  17&nbsp;#  Replacing line 7, above, with
  18&nbsp;#+   cat &#62; $Newfile &#60;&#60;End-of-message
  19&nbsp;#+       ^^^^^^^^^^
  20&nbsp;#+ writes the output to the file $Newfile, rather than to stdout.
  21&nbsp;
  22&nbsp;exit 0
  23&nbsp;
  24&nbsp;
  25&nbsp;#--------------------------------------------
  26&nbsp;# Code below disabled, due to "exit 0" above.
  27&nbsp;
  28&nbsp;# S.C. points out that the following also works.
  29&nbsp;echo "-------------------------------------
  30&nbsp;This is line 1 of the message.
  31&nbsp;This is line 2 of the message.
  32&nbsp;This is line 3 of the message.
  33&nbsp;This is line 4 of the message.
  34&nbsp;This is the last line of the message.
  35&nbsp;-------------------------------------"
  36&nbsp;# However, text may not include double quotes unless they are escaped.</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="LIMITSTRDASH"
></A
></P
><P
>The <TT
CLASS="OPTION"
>-</TT
> option to mark a here document limit string
	(<TT
CLASS="USERINPUT"
><B
>&#60;&#60;-LimitString</B
></TT
>) suppresses leading
	tabs (but not spaces) in the output. This may be useful in making
	a script more readable.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX71A"
></A
><P
><B
>Example 19-4. Multi-line message, with tabs suppressed</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# Same as previous example, but...
   3&nbsp;
   4&nbsp;#  The - option to a here document &#60;&#60;-
   5&nbsp;#+ suppresses leading tabs in the body of the document,
   6&nbsp;#+ but *not* spaces.
   7&nbsp;
   8&nbsp;cat &#60;&#60;-ENDOFMESSAGE
   9&nbsp;	This is line 1 of the message.
  10&nbsp;	This is line 2 of the message.
  11&nbsp;	This is line 3 of the message.
  12&nbsp;	This is line 4 of the message.
  13&nbsp;	This is the last line of the message.
  14&nbsp;ENDOFMESSAGE
  15&nbsp;# The output of the script will be flush left.
  16&nbsp;# Leading tab in each line will not show.
  17&nbsp;
  18&nbsp;# Above 5 lines of "message" prefaced by a tab, not spaces.
  19&nbsp;# Spaces not affected by   &#60;&#60;-  .
  20&nbsp;
  21&nbsp;# Note that this option has no effect on *embedded* tabs.
  22&nbsp;
  23&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HEREPASSP"
></A
></P
><P
>A <I
CLASS="FIRSTTERM"
>here document</I
> supports parameter and
	command substitution.  It is therefore possible to pass different
	parameters to the body of the here document, changing its output
	accordingly.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX71B"
></A
><P
><B
>Example 19-5. Here document with replaceable parameters</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# Another 'cat' here document, using parameter substitution.
   3&nbsp;
   4&nbsp;# Try it with no command-line parameters,   ./scriptname
   5&nbsp;# Try it with one command-line parameter,   ./scriptname Mortimer
   6&nbsp;# Try it with one two-word quoted command-line parameter,
   7&nbsp;#                           ./scriptname "Mortimer Jones"
   8&nbsp;
   9&nbsp;CMDLINEPARAM=1     #  Expect at least command-line parameter.
  10&nbsp;
  11&nbsp;if [ $# -ge $CMDLINEPARAM ]
  12&nbsp;then
  13&nbsp;  NAME=$1          #  If more than one command-line param,
  14&nbsp;                   #+ then just take the first.
  15&nbsp;else
  16&nbsp;  NAME="John Doe"  #  Default, if no command-line parameter.
  17&nbsp;fi  
  18&nbsp;
  19&nbsp;RESPONDENT="the author of this fine script"  
  20&nbsp;  
  21&nbsp;
  22&nbsp;cat &#60;&#60;Endofmessage
  23&nbsp;
  24&nbsp;Hello, there, $NAME.
  25&nbsp;Greetings to you, $NAME, from $RESPONDENT.
  26&nbsp;
  27&nbsp;# This comment shows up in the output (why?).
  28&nbsp;
  29&nbsp;Endofmessage
  30&nbsp;
  31&nbsp;# Note that the blank lines show up in the output.
  32&nbsp;# So does the comment.
  33&nbsp;
  34&nbsp;exit</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HEREPARAMSUB"
></A
></P
><P
>This is a useful script containing a <I
CLASS="FIRSTTERM"
>here
        document</I
> with parameter substitution.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX72"
></A
><P
><B
>Example 19-6. Upload a file pair to <I
CLASS="FIRSTTERM"
>Sunsite</I
> incoming
	  directory</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# upload.sh
   3&nbsp;
   4&nbsp;#  Upload file pair (Filename.lsm, Filename.tar.gz)
   5&nbsp;#+ to incoming directory at Sunsite/UNC (ibiblio.org).
   6&nbsp;#  Filename.tar.gz is the tarball itself.
   7&nbsp;#  Filename.lsm is the descriptor file.
   8&nbsp;#  Sunsite requires "lsm" file, otherwise will bounce contributions.
   9&nbsp;
  10&nbsp;
  11&nbsp;E_ARGERROR=85
  12&nbsp;
  13&nbsp;if [ -z "$1" ]
  14&nbsp;then
  15&nbsp;  echo "Usage: `basename $0` Filename-to-upload"
  16&nbsp;  exit $E_ARGERROR
  17&nbsp;fi  
  18&nbsp;
  19&nbsp;
  20&nbsp;Filename=`basename $1`           # Strips pathname out of file name.
  21&nbsp;
  22&nbsp;Server="ibiblio.org"
  23&nbsp;Directory="/incoming/Linux"
  24&nbsp;#  These need not be hard-coded into script,
  25&nbsp;#+ but may instead be changed to command-line argument.
  26&nbsp;
  27&nbsp;Password="your.e-mail.address"   # Change above to suit.
  28&nbsp;
  29&nbsp;ftp -n $Server &#60;&#60;End-Of-Session
  30&nbsp;# -n option disables auto-logon
  31&nbsp;
  32&nbsp;user anonymous "$Password"       #  If this doesn't work, then try:
  33&nbsp;                                 #  quote user anonymous "$Password"
  34&nbsp;binary
  35&nbsp;bell                             # Ring 'bell' after each file transfer.
  36&nbsp;cd $Directory
  37&nbsp;put "$Filename.lsm"
  38&nbsp;put "$Filename.tar.gz"
  39&nbsp;bye
  40&nbsp;End-Of-Session
  41&nbsp;
  42&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HEREESC"
></A
></P
><P
>Quoting or escaping the <SPAN
CLASS="QUOTE"
>"limit string"</SPAN
> at the
        head of a here document disables parameter substitution within its
	body. The reason for this is that <I
CLASS="FIRSTTERM"
>quoting/escaping the
	limit string</I
> effectively <A
HREF="escapingsection.html#ESCP"
>escapes</A
> the <SPAN
CLASS="TOKEN"
>$</SPAN
>,
	<SPAN
CLASS="TOKEN"
>`</SPAN
>, and <SPAN
CLASS="TOKEN"
>\</SPAN
> <A
HREF="special-chars.html#SCHARLIST"
>special characters</A
>, and causes them to
	be interpreted literally. (Thank you, Allen Halsey, for pointing
	this out.)</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="EX71C"
></A
><P
><B
>Example 19-7. Parameter substitution turned off</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;#  A 'cat' here-document, but with parameter substitution disabled.
   3&nbsp;
   4&nbsp;NAME="John Doe"
   5&nbsp;RESPONDENT="the author of this fine script"  
   6&nbsp;
   7&nbsp;cat &#60;&#60;'Endofmessage'
   8&nbsp;
   9&nbsp;Hello, there, $NAME.
  10&nbsp;Greetings to you, $NAME, from $RESPONDENT.
  11&nbsp;
  12&nbsp;Endofmessage
  13&nbsp;
  14&nbsp;#   No parameter substitution when the "limit string" is quoted or escaped.
  15&nbsp;#   Either of the following at the head of the here document would have
  16&nbsp;#+  the same effect.
  17&nbsp;#   cat &#60;&#60;"Endofmessage"
  18&nbsp;#   cat &#60;&#60;\Endofmessage
  19&nbsp;
  20&nbsp;
  21&nbsp;
  22&nbsp;#   And, likewise:
  23&nbsp;
  24&nbsp;cat &#60;&#60;"SpecialCharTest"
  25&nbsp;
  26&nbsp;Directory listing would follow
  27&nbsp;if limit string were not quoted.
  28&nbsp;`ls -l`
  29&nbsp;
  30&nbsp;Arithmetic expansion would take place
  31&nbsp;if limit string were not quoted.
  32&nbsp;$((5 + 3))
  33&nbsp;
  34&nbsp;A a single backslash would echo
  35&nbsp;if limit string were not quoted.
  36&nbsp;\\
  37&nbsp;
  38&nbsp;SpecialCharTest
  39&nbsp;
  40&nbsp;
  41&nbsp;exit</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HERELIT"
></A
></P
><P
>Disabling parameter substitution permits outputting literal text.
        Generating scripts or even program code is one use for this.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="GENERATESCRIPT"
></A
><P
><B
>Example 19-8. A script that generates another script</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# generate-script.sh
   3&nbsp;# Based on an idea by Albert Reiner.
   4&nbsp;
   5&nbsp;OUTFILE=generated.sh         # Name of the file to generate.
   6&nbsp;
   7&nbsp;
   8&nbsp;# -----------------------------------------------------------
   9&nbsp;# 'Here document containing the body of the generated script.
  10&nbsp;(
  11&nbsp;cat &#60;&#60;'EOF'
  12&nbsp;#!/bin/bash
  13&nbsp;
  14&nbsp;echo "This is a generated shell script."
  15&nbsp;#  Note that since we are inside a subshell,
  16&nbsp;#+ we can't access variables in the "outside" script.
  17&nbsp;
  18&nbsp;echo "Generated file will be named: $OUTFILE"
  19&nbsp;#  Above line will not work as normally expected
  20&nbsp;#+ because parameter expansion has been disabled.
  21&nbsp;#  Instead, the result is literal output.
  22&nbsp;
  23&nbsp;a=7
  24&nbsp;b=3
  25&nbsp;
  26&nbsp;let "c = $a * $b"
  27&nbsp;echo "c = $c"
  28&nbsp;
  29&nbsp;exit 0
  30&nbsp;EOF
  31&nbsp;) &#62; $OUTFILE
  32&nbsp;# -----------------------------------------------------------
  33&nbsp;
  34&nbsp;#  Quoting the 'limit string' prevents variable expansion
  35&nbsp;#+ within the body of the above 'here document.'
  36&nbsp;#  This permits outputting literal strings in the output file.
  37&nbsp;
  38&nbsp;if [ -f "$OUTFILE" ]
  39&nbsp;then
  40&nbsp;  chmod 755 $OUTFILE
  41&nbsp;  # Make the generated file executable.
  42&nbsp;else
  43&nbsp;  echo "Problem in creating file: \"$OUTFILE\""
  44&nbsp;fi
  45&nbsp;
  46&nbsp;#  This method also works for generating
  47&nbsp;#+ C programs, Perl programs, Python programs, Makefiles,
  48&nbsp;#+ and the like.
  49&nbsp;
  50&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HERECS"
></A
></P
><P
>        It is possible to set a variable from the output of a here document.
	This is actually a devious form of <A
HREF="commandsub.html#COMMANDSUBREF"
>command substitution</A
>.
	<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;variable=$(cat &#60;&#60;SETVAR
   2&nbsp;This variable
   3&nbsp;runs over multiple lines.
   4&nbsp;SETVAR
   5&nbsp;)
   6&nbsp;
   7&nbsp;echo "$variable"</PRE
></TD
></TR
></TABLE
>
      </P
><P
><A
NAME="HEREFUNC"
></A
></P
><P
>A here document can supply input to a function in the same
        script.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="HF"
></A
><P
><B
>Example 19-9. Here documents and functions</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# here-function.sh
   3&nbsp;
   4&nbsp;GetPersonalData ()
   5&nbsp;{
   6&nbsp;  read firstname
   7&nbsp;  read lastname
   8&nbsp;  read address
   9&nbsp;  read city 
  10&nbsp;  read state 
  11&nbsp;  read zipcode
  12&nbsp;} # This certainly appears to be an interactive function, but . . .
  13&nbsp;
  14&nbsp;
  15&nbsp;# Supply input to the above function.
  16&nbsp;GetPersonalData &#60;&#60;RECORD001
  17&nbsp;Bozo
  18&nbsp;Bozeman
  19&nbsp;2726 Nondescript Dr.
  20&nbsp;Bozeman
  21&nbsp;MT
  22&nbsp;21226
  23&nbsp;RECORD001
  24&nbsp;
  25&nbsp;
  26&nbsp;echo
  27&nbsp;echo "$firstname $lastname"
  28&nbsp;echo "$address"
  29&nbsp;echo "$city, $state $zipcode"
  30&nbsp;echo
  31&nbsp;
  32&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="ANONHEREDOC0"
></A
></P
><P
>It is possible to use <SPAN
CLASS="TOKEN"
>:</SPAN
> as a dummy command
        accepting output from a here document. This, in effect, creates an
	<SPAN
CLASS="QUOTE"
>"anonymous"</SPAN
> here document.</P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="ANONHEREDOC"
></A
><P
><B
>Example 19-10. <SPAN
CLASS="QUOTE"
>"Anonymous"</SPAN
> Here Document</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;: &#60;&#60;TESTVARIABLES
   4&nbsp;${HOSTNAME?}${USER?}${MAIL?}  # Print error message if one of the variables not set.
   5&nbsp;TESTVARIABLES
   6&nbsp;
   7&nbsp;exit $?</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="CBLOCK1"
></A
></P
><DIV
CLASS="TIP"
><TABLE
CLASS="TIP"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/tip.png"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>A variation of the above technique permits <SPAN
CLASS="QUOTE"
>"commenting
        out"</SPAN
> blocks of code.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="COMMENTBLOCK"
></A
><P
><B
>Example 19-11. Commenting out a block of code</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# commentblock.sh
   3&nbsp;
   4&nbsp;: &#60;&#60;COMMENTBLOCK
   5&nbsp;echo "This line will not echo."
   6&nbsp;This is a comment line missing the "#" prefix.
   7&nbsp;This is another comment line missing the "#" prefix.
   8&nbsp;
   9&nbsp;&#38;*@!!++=
  10&nbsp;The above line will cause no error message,
  11&nbsp;because the Bash interpreter will ignore it.
  12&nbsp;COMMENTBLOCK
  13&nbsp;
  14&nbsp;echo "Exit value of above \"COMMENTBLOCK\" is $?."   # 0
  15&nbsp;# No error shown.
  16&nbsp;echo
  17&nbsp;
  18&nbsp;
  19&nbsp;#  The above technique also comes in useful for commenting out
  20&nbsp;#+ a block of working code for debugging purposes.
  21&nbsp;#  This saves having to put a "#" at the beginning of each line,
  22&nbsp;#+ then having to go back and delete each "#" later.
  23&nbsp;#  Note that the use of of colon, above, is optional.
  24&nbsp;
  25&nbsp;echo "Just before commented-out code block."
  26&nbsp;#  The lines of code between the double-dashed lines will not execute.
  27&nbsp;#  ===================================================================
  28&nbsp;: &#60;&#60;DEBUGXXX
  29&nbsp;for file in *
  30&nbsp;do
  31&nbsp; cat "$file"
  32&nbsp;done
  33&nbsp;DEBUGXXX
  34&nbsp;#  ===================================================================
  35&nbsp;echo "Just after commented-out code block."
  36&nbsp;
  37&nbsp;exit 0
  38&nbsp;
  39&nbsp;
  40&nbsp;
  41&nbsp;######################################################################
  42&nbsp;#  Note, however, that if a bracketed variable is contained within
  43&nbsp;#+ the commented-out code block,
  44&nbsp;#+ then this could cause problems.
  45&nbsp;#  for example:
  46&nbsp;
  47&nbsp;
  48&nbsp;#/!/bin/bash
  49&nbsp;
  50&nbsp;  : &#60;&#60;COMMENTBLOCK
  51&nbsp;  echo "This line will not echo."
  52&nbsp;  &#38;*@!!++=
  53&nbsp;  ${foo_bar_bazz?}
  54&nbsp;  $(rm -rf /tmp/foobar/)
  55&nbsp;  $(touch my_build_directory/cups/Makefile)
  56&nbsp;COMMENTBLOCK
  57&nbsp;
  58&nbsp;
  59&nbsp;$ sh commented-bad.sh
  60&nbsp;commented-bad.sh: line 3: foo_bar_bazz: parameter null or not set
  61&nbsp;
  62&nbsp;# The remedy for this is to strong-quote the 'COMMENTBLOCK' in line 49, above.
  63&nbsp;
  64&nbsp;  : &#60;&#60;'COMMENTBLOCK'
  65&nbsp;
  66&nbsp;# Thank you, Kurt Pfeifle, for pointing this out.</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
><A
NAME="HSELFDOC"
></A
></P
><DIV
CLASS="TIP"
><TABLE
CLASS="TIP"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/tip.png"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Yet another twist of this nifty trick makes
        <SPAN
CLASS="QUOTE"
>"self-documenting"</SPAN
> scripts possible.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="SELFDOCUMENT"
></A
><P
><B
>Example 19-12. A self-documenting script</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# self-document.sh: self-documenting script
   3&nbsp;# Modification of "colm.sh".
   4&nbsp;
   5&nbsp;DOC_REQUEST=70
   6&nbsp;
   7&nbsp;if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
   8&nbsp;then
   9&nbsp;  echo; echo "Usage: $0 [directory-name]"; echo
  10&nbsp;  sed --silent -e '/DOCUMENTATIONXX$/,/^DOCUMENTATIONXX$/p' "$0" |
  11&nbsp;  sed -e '/DOCUMENTATIONXX$/d'; exit $DOC_REQUEST; fi
  12&nbsp;
  13&nbsp;
  14&nbsp;: &#60;&#60;DOCUMENTATIONXX
  15&nbsp;List the statistics of a specified directory in tabular format.
  16&nbsp;---------------------------------------------------------------
  17&nbsp;The command-line parameter gives the directory to be listed.
  18&nbsp;If no directory specified or directory specified cannot be read,
  19&nbsp;then list the current working directory.
  20&nbsp;
  21&nbsp;DOCUMENTATIONXX
  22&nbsp;
  23&nbsp;if [ -z "$1" -o ! -r "$1" ]
  24&nbsp;then
  25&nbsp;  directory=.
  26&nbsp;else
  27&nbsp;  directory="$1"
  28&nbsp;fi  
  29&nbsp;
  30&nbsp;echo "Listing of "$directory":"; echo
  31&nbsp;(printf "PERMISSIONS LINKS OWNER GROUP SIZE MONTH DAY HH:MM PROG-NAME\n" \
  32&nbsp;; ls -l "$directory" | sed 1d) | column -t
  33&nbsp;
  34&nbsp;exit 0</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>Using a <A
HREF="here-docs.html#CATSCRIPTREF"
>cat script</A
> is an
        alternate way of accomplishing this.</P
><P
>      <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;DOC_REQUEST=70
   2&nbsp;
   3&nbsp;if [ "$1" = "-h"  -o "$1" = "--help" ]     # Request help.
   4&nbsp;then                                       # Use a "cat script" . . .
   5&nbsp;  cat &#60;&#60;DOCUMENTATIONXX
   6&nbsp;List the statistics of a specified directory in tabular format.
   7&nbsp;---------------------------------------------------------------
   8&nbsp;The command-line parameter gives the directory to be listed.
   9&nbsp;If no directory specified or directory specified cannot be read,
  10&nbsp;then list the current working directory.
  11&nbsp;
  12&nbsp;DOCUMENTATIONXX
  13&nbsp;exit $DOC_REQUEST
  14&nbsp;fi</PRE
></TD
></TR
></TABLE
>
      </P
><P
>See also <A
HREF="contributed-scripts.html#ISSPAMMER2"
>Example A-28</A
>, <A
HREF="contributed-scripts.html#PETALS"
>Example A-40</A
>,
        <A
HREF="contributed-scripts.html#QKY"
>Example A-41</A
>, and <A
HREF="contributed-scripts.html#NIM"
>Example A-42</A
> for more examples
        of self-documenting scripts.</P
><P
><A
NAME="HERETEMP"
></A
></P
><DIV
CLASS="NOTE"
><TABLE
CLASS="NOTE"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/note.png"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Here documents create temporary files, but these
	    files are deleted after opening and are not accessible to
	    any other process.</P
><P
>	      <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="SCREEN"
> <TT
CLASS="PROMPT"
>bash$ </TT
><TT
CLASS="USERINPUT"
><B
>bash -c 'lsof -a -p $$ -d0' &#60;&#60; EOF</B
></TT
>
 <TT
CLASS="PROMPT"
>&#62; </TT
><TT
CLASS="USERINPUT"
><B
>EOF</B
></TT
>
 <TT
CLASS="COMPUTEROUTPUT"
>lsof    1213 bozo    0r   REG    3,5    0 30386 /tmp/t1213-0-sh (deleted)</TT
>
 	      </PRE
></TD
></TR
></TABLE
>
	  </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="CAUTION"
><TABLE
CLASS="CAUTION"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/caution.png"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Some utilities will not work inside a
	  <I
CLASS="FIRSTTERM"
>here document</I
>.</P
></TD
></TR
></TABLE
></DIV
><P
><A
NAME="INDENTEDLS"
></A
></P
><DIV
CLASS="WARNING"
><TABLE
CLASS="WARNING"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/warning.png"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The closing <I
CLASS="FIRSTTERM"
>limit string</I
>,
	  on the final line of a here document, must start in the
	  <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>first</I
></SPAN
> character position. There can
	  be <SPAN
CLASS="emphasis"
><I
CLASS="EMPHASIS"
>no leading whitespace</I
></SPAN
>. Trailing
	  whitespace after the limit string likewise causes unexpected
	  behavior. The whitespace prevents the limit string from being
	  recognized.
  
          <A
NAME="AEN17822"
HREF="#FTN.AEN17822"
>[1]</A
>
	  
	  </P
><P
>	 <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;
   3&nbsp;echo "----------------------------------------------------------------------"
   4&nbsp;
   5&nbsp;cat &#60;&#60;LimitString
   6&nbsp;echo "This is line 1 of the message inside the here document."
   7&nbsp;echo "This is line 2 of the message inside the here document."
   8&nbsp;echo "This is the final line of the message inside the here document."
   9&nbsp;     LimitString
  10&nbsp;#^^^^Indented limit string. Error! This script will not behave as expected.
  11&nbsp;
  12&nbsp;echo "----------------------------------------------------------------------"
  13&nbsp;
  14&nbsp;#  These comments are outside the 'here document',
  15&nbsp;#+ and should not echo.
  16&nbsp;
  17&nbsp;echo "Outside the here document."
  18&nbsp;
  19&nbsp;exit 0
  20&nbsp;
  21&nbsp;echo "This line had better not echo."  # Follows an 'exit' command.</PRE
></TD
></TR
></TABLE
>
	 </P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="CAUTION"
><TABLE
CLASS="CAUTION"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="common/caution.png"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
><A
NAME="EXCLLS"
></A
>Some people very cleverly use a
          single <SPAN
CLASS="TOKEN"
>!</SPAN
> as a limit string. But, that's not
          necessarily a good idea.</P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;# This works.
   2&nbsp;cat &#60;&#60;!
   3&nbsp;Hello!
   4&nbsp;! Three more exclamations !!!
   5&nbsp;!
   6&nbsp;
   7&nbsp;
   8&nbsp;# But . . .
   9&nbsp;cat &#60;&#60;!
  10&nbsp;Hello!
  11&nbsp;Single exclamation point follows!
  12&nbsp;!
  13&nbsp;!
  14&nbsp;# Crashes with an error message.
  15&nbsp;
  16&nbsp;
  17&nbsp;# However, the following will work.
  18&nbsp;cat &#60;&#60;EOF
  19&nbsp;Hello!
  20&nbsp;Single exclamation point follows!
  21&nbsp;!
  22&nbsp;EOF
  23&nbsp;# It's safer to use a multi-character limit string.</PRE
></TD
></TR
></TABLE
></P
></TD
></TR
></TABLE
></DIV
><P
>For those tasks too complex for a <I
CLASS="FIRSTTERM"
>here
	  document</I
>, consider using the
	  <TT
CLASS="REPLACEABLE"
><I
>expect</I
></TT
> scripting language, which
	  was specifically designed for feeding input into interactive
	  programs.</P
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="AEN17837"
></A
>19.1. Here Strings</H1
><P
><A
NAME="HERESTRINGSREF"
></A
></P
><A
NAME="AEN17841"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
CLASS="LITERALLAYOUT"
>A&nbsp;<I
CLASS="FIRSTTERM"
>here string</I
>&nbsp;can&nbsp;be&nbsp;considered&nbsp;as&nbsp;a&nbsp;stripped-down&nbsp;form&nbsp;of&nbsp;a&nbsp;<I
CLASS="FIRSTTERM"
>here document</I
>.<br>
It&nbsp;consists&nbsp;of&nbsp;nothing&nbsp;more&nbsp;than&nbsp;<B
CLASS="COMMAND"
>COMMAND &#60;&#60;&#60; $WORD</B
>,<br>
where&nbsp;<TT
CLASS="VARNAME"
>$WORD</TT
>&nbsp;is&nbsp;expanded&nbsp;and&nbsp;fed&nbsp;to&nbsp;the&nbsp;<TT
CLASS="FILENAME"
>stdin</TT
>&nbsp;of&nbsp;<B
CLASS="COMMAND"
>COMMAND</B
>.<br>
	&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</P
></BLOCKQUOTE
><P
>As a simple example, consider this alternative to the <A
HREF="internal.html#ECHOGREPREF"
>echo-grep</A
> construction.</P
><P
>	  <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;# Instead of:
   2&nbsp;if echo "$VAR" | grep -q txt   # if [[ $VAR = *txt* ]]
   3&nbsp;# etc.
   4&nbsp;
   5&nbsp;# Try:
   6&nbsp;if grep -q "txt" &#60;&#60;&#60; "$VAR"
   7&nbsp;then   #         ^^^
   8&nbsp;   echo "$VAR contains the substring sequence \"txt\""
   9&nbsp;fi
  10&nbsp;# Thank you, Sebastian Kaminski, for the suggestion.</PRE
></TD
></TR
></TABLE
>
        </P
><P
><A
NAME="HSREAD"
></A
></P
><P
>Or, in combination with <A
HREF="internal.html#READREF"
>read</A
>:</P
><P
>	<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;String="This is a string of words."
   2&nbsp;
   3&nbsp;read -r -a Words &#60;&#60;&#60; "$String"
   4&nbsp;#  The -a option to "read"
   5&nbsp;#+ assigns the resulting values to successive members of an array.
   6&nbsp;
   7&nbsp;echo "First word in String is:    ${Words[0]}"   # This
   8&nbsp;echo "Second word in String is:   ${Words[1]}"   # is
   9&nbsp;echo "Third word in String is:    ${Words[2]}"   # a
  10&nbsp;echo "Fourth word in String is:   ${Words[3]}"   # string
  11&nbsp;echo "Fifth word in String is:    ${Words[4]}"   # of
  12&nbsp;echo "Sixth word in String is:    ${Words[5]}"   # words.
  13&nbsp;echo "Seventh word in String is:  ${Words[6]}"   # (null)
  14&nbsp;                                                 # Past end of $String.
  15&nbsp;
  16&nbsp;# Thank you, Francisco Lobo, for the suggestion.</PRE
></TD
></TR
></TABLE
>
        </P
><P
><A
NAME="HSLOOP"
></A
>It is, of course, possible to feed
	  the output of a <I
CLASS="FIRSTTERM"
>here string</I
>
	  into the <TT
CLASS="FILENAME"
>stdin</TT
> of a <A
HREF="loops.html#LOOPREF00"
>loop</A
>.</P
><P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;# As Seamus points out . . .
   2&nbsp;
   3&nbsp;ArrayVar=( element0 element1 element2 {A..D} )
   4&nbsp;
   5&nbsp;while read element ; do
   6&nbsp;  echo "$element" 1&#62;&#38;2
   7&nbsp;done &#60;&#60;&#60; $(echo ${ArrayVar[*]})
   8&nbsp;
   9&nbsp;# element0 element1 element2 A B C D</PRE
></TD
></TR
></TABLE
></P
><P
><A
NAME="HSPRE"
></A
></P
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="PREPENDEX"
></A
><P
><B
>Example 19-13. Prepending a line to a file</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;# prepend.sh: Add text at beginning of file.
   3&nbsp;#
   4&nbsp;#  Example contributed by Kenny Stauffer,
   5&nbsp;#+ and slightly modified by document author.
   6&nbsp;
   7&nbsp;
   8&nbsp;E_NOSUCHFILE=85
   9&nbsp;
  10&nbsp;read -p "File: " file   # -p arg to 'read' displays prompt.
  11&nbsp;if [ ! -e "$file" ]
  12&nbsp;then   # Bail out if no such file.
  13&nbsp;  echo "File $file not found."
  14&nbsp;  exit $E_NOSUCHFILE
  15&nbsp;fi
  16&nbsp;
  17&nbsp;read -p "Title: " title
  18&nbsp;cat - $file &#60;&#60;&#60;$title &#62; $file.new
  19&nbsp;
  20&nbsp;echo "Modified file is $file.new"
  21&nbsp;
  22&nbsp;exit  # Ends script execution.
  23&nbsp;
  24&nbsp;  from 'man bash':
  25&nbsp;  Here Strings
  26&nbsp;  	A variant of here documents, the format is:
  27&nbsp;  
  28&nbsp;  		&#60;&#60;&#60;word
  29&nbsp;  
  30&nbsp;  	The word is expanded and supplied to the command on its standard input.
  31&nbsp;
  32&nbsp;
  33&nbsp;  Of course, the following also works:
  34&nbsp;   sed -e '1i\
  35&nbsp;   Title: ' $file</PRE
></TD
></TR
></TABLE
><HR></DIV
><DIV
CLASS="EXAMPLE"
><HR><A
NAME="MAILBOXGREP"
></A
><P
><B
>Example 19-14. Parsing a mailbox</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="PROGRAMLISTING"
>   1&nbsp;#!/bin/bash
   2&nbsp;#  Script by Francisco Lobo,
   3&nbsp;#+ and slightly modified and commented by ABS Guide author.
   4&nbsp;#  Used in ABS Guide with permission. (Thank you!)
   5&nbsp;
   6&nbsp;# This script will not run under Bash versions -lt 3.0.
   7&nbsp;
   8&nbsp;
   9&nbsp;E_MISSING_ARG=87
  10&nbsp;if [ -z "$1" ]
  11&nbsp;then
  12&nbsp;  echo "Usage: $0 mailbox-file"
  13&nbsp;  exit $E_MISSING_ARG
  14&nbsp;fi
  15&nbsp;
  16&nbsp;mbox_grep()  # Parse mailbox file.
  17&nbsp;{
  18&nbsp;    declare -i body=0 match=0
  19&nbsp;    declare -a date sender
  20&nbsp;    declare mail header value
  21&nbsp;
  22&nbsp;
  23&nbsp;    while IFS= read -r mail
  24&nbsp;#         ^^^^                 Reset $IFS.
  25&nbsp;#  Otherwise "read" will strip leading &#38; trailing space from its input.
  26&nbsp;
  27&nbsp;   do
  28&nbsp;       if [[ $mail =~ ^From  ]]   # Match "From" field in message.
  29&nbsp;       then
  30&nbsp;          (( body  = 0 ))           # "Zero out" variables.
  31&nbsp;          (( match = 0 ))
  32&nbsp;          unset date
  33&nbsp;
  34&nbsp;       elif (( body ))
  35&nbsp;       then
  36&nbsp;            (( match ))
  37&nbsp;            #  echo "$mail"
  38&nbsp;            #  Uncomment above line if you want entire body
  39&nbsp;            #+ of message to display.
  40&nbsp;
  41&nbsp;   elif [[ $mail ]]; then
  42&nbsp;      IFS=: read -r header value &#60;&#60;&#60; "$mail"
  43&nbsp;      #                          ^^^  "here string"
  44&nbsp;
  45&nbsp;      case "$header" in
  46&nbsp;      [Ff][Rr][Oo][Mm] ) [[ $value =~ "$2" ]] &#38;&#38; (( match++ )) ;;
  47&nbsp;      # Match "From" line.
  48&nbsp;      [Dd][Aa][Tt][Ee] ) read -r -a date &#60;&#60;&#60; "$value" ;;
  49&nbsp;      #                                  ^^^
  50&nbsp;      # Match "Date" line.
  51&nbsp;      [Rr][Ee][Cc][Ee][Ii][Vv][Ee][Dd] ) read -r -a sender &#60;&#60;&#60; "$value" ;;
  52&nbsp;      #                                                    ^^^
  53&nbsp;      # Match IP Address (may be spoofed).
  54&nbsp;      esac
  55&nbsp;
  56&nbsp;       else
  57&nbsp;          (( body++ ))
  58&nbsp;          (( match  )) &#38;&#38;
  59&nbsp;          echo "MESSAGE ${date:+of: ${date[*]} }"
  60&nbsp;       #    Entire $date array             ^
  61&nbsp;          echo "IP address of sender: ${sender[1]}"
  62&nbsp;       #    Second field of "Received" line    ^
  63&nbsp;
  64&nbsp;       fi
  65&nbsp;
  66&nbsp;
  67&nbsp;    done &#60; "$1" # Redirect stdout of file into loop.
  68&nbsp;}
  69&nbsp;
  70&nbsp;
  71&nbsp;mbox_grep "$1"  # Send mailbox file to function.
  72&nbsp;
  73&nbsp;exit $?
  74&nbsp;
  75&nbsp;# Exercises:
  76&nbsp;# ---------
  77&nbsp;# 1) Break the single function, above, into multiple functions,
  78&nbsp;#+   for the sake of readability.
  79&nbsp;# 2) Add additional parsing to the script, checking for various keywords.
  80&nbsp;
  81&nbsp;
  82&nbsp;
  83&nbsp;$ mailbox_grep.sh scam_mail
  84&nbsp;  MESSAGE of Thu, 5 Jan 2006 08:00:56 -0500 (EST) 
  85&nbsp;  IP address of sender: 196.3.62.4</PRE
></TD
></TR
></TABLE
><HR></DIV
><P
>Exercise: Find other uses for <I
CLASS="FIRSTTERM"
>here
           strings</I
>, such as, for example, <A
HREF="mathc.html#GOLDENRATIO"
>feeding input to
           <I
CLASS="FIRSTTERM"
>dc</I
></A
>.</P
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN17822"
HREF="here-docs.html#AEN17822"
>[1]</A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Except, as Dennis Benzinger points out,
          if <A
HREF="here-docs.html#LIMITSTRDASH"
>using
          <B
CLASS="COMMAND"
>&#60;&#60;-</B
> to suppress
          tabs</A
>.</P
></TD
></TR
></TABLE
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="globbingref.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="io-redirection.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Globbing</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="part5.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>I/O Redirection</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>