.. include:: ../header.txt

.. _here:

Here Documents
===========================

.. index:: here documents, <<

:title:`Linux for Programmers and Users`, Section 5.6.2 and 5.17

This rather peculiar metacharacter (**\ <<**) allows us to provide complex,
multi-line input to a command.  Perhaps its most common usage is in a shell
script used with the :command:`cat` command to display a lengthy description
to the user.

An example might illustrate its usage best::

    $ cat << STOP
    > Today, we hope that you learn a great deal about Unix.
    > We are using Linux as our Unix system.
    > There are many versions of Unix systems, including:
    >     UNIX, Solaris, BSD, AIX, HP-UX and Linux.
    > References to UNIX, as it used to be spelled, are considered
    > references to the UNIX from AT&T Bell Labs.  Unix is a 
    > generic term refering to all Unix like systems.
    > STOP
    Today, we hope that you learn a great deal about Unix.
    We are using Linux as our Unix system.
    There are many versions of Unix systems, including:
        UNIX, Solaris, BSD, AIX, HP-UX and Linux.
    References to UNIX, as it used to be spelled, are considered
    references to the UNIX from AT&T Bell Labs.  Unix is a 
    generic term refering to all Unix like systems.

In the above example, the `\ >` characters at the beginning of each line are
produced by the :command:`cat` command, which is reading from standard input.
Those characters will not be present in shell script.

.. note::

    * The :ref:`here` metacharacter produced the end-of-file character.  It was
      not necessary to type `Cntrl-d` above.

    * In the above example, `STOP` is an identifier.  Any string may be used
      as the terminal string.

Strip Leading Tabs
-------------------

.. index:: <<-

The BASH shell provides an extra feature to :ref:`here`. When a dash is
added to the metacharacters, ``<<-``, then leading tab characters are
removed in the displayed information. This might might make formating in
shell script look neater because the text can be indented.

::

    $ cat <<- STOP
    >       An indented line ...
    >       or two ...
    > STOP
    An indented line ...
    or two ...