[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 9. File inclusion

`m4` allows you to include named files at any point in the input.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.1 Including named files

There are two builtin macros in `m4` for including files:

Builtin: include (file)
Builtin: sinclude (file)

  Both macros cause the file named file to be read by `m4`. When the end of the file is reached, input is resumed from the previous input file.

  The expansion of `include` and `sinclude` is therefore the contents of file.

  If file does not exist (or cannot be read), the expansion is void, and `include` will fail with an error while `sinclude` is silent. The empty string counts as a file that does not exist.

  The macros `include` and `sinclude` are recognized only with parameters.

    include(`none')
    error-->m4:stdin:1: cannot open `none': No such file or directory
    ⇒
    include()
    error-->m4:stdin:2: cannot open `': No such file or directory
    ⇒
    sinclude(`none')
    ⇒
    sinclude()
    ⇒

The rest of this section assumes that `m4` is invoked with the ``-I'` option (see section Invoking m4) pointing to the ``m4-1.4.8/examples'` directory shipped as part of the GNU `m4` package. The file ``m4-1.4.8/examples/incl.m4'` in the distribution contains the lines:

    Include file start
    foo
    Include file end

Normally file inclusion is used to insert the contents of a file into the input stream. The contents of the file will be read by `m4` and macro calls in the file will be expanded:

    define(`foo', `FOO')
    ⇒
    include(`incl.m4')
    ⇒Include file start
    ⇒FOO
    ⇒Include file end
    ⇒

The fact that `include` and `sinclude` expand to the contents of the file can be used to define macros that operate on entire files. Here is an example, which defines ``bar'` to expand to the contents of ``incl.m4'`:

    define(`bar', include(`incl.m4'))
    ⇒
    This is `bar':  >>bar<<
    ⇒This is bar:  >>Include file start
    ⇒foo
    ⇒Include file end
    ⇒<<

This use of `include` is not trivial, though, as files can contain quotes, commas, and parentheses, which can interfere with the way the `m4` parser works. GNU `m4` seamlessly concatenates the file contents with the next character, even if the included file ended in the middle of a comment, string, or macro call. These conditions are only treated as end of file errors if specified as input files on the command line.

In GNU `m4`, an alternative method of reading files is using `undivert` (see section Undiverting output) on a named file.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 9.2 Searching for include files

GNU `m4` allows included files to be found in other directories than the current working directory.

If the ``--prepend-include'` or ``-B'` command-line option was provided (see section Invoking m4), those directories are searched first, in reverse order that those options were listed on the command line. Then `m4` looks in the current working directory. Next comes the directories specified with the ``--include'` or ``-I'` option, in the order found on the command line. Finally, if the `M4PATH` environment variable is set, it is expected to contain a colon-separated list of directories, which will be searched in order.

If the automatic search for include-files causes trouble, the ``p'` debug flag (see section Controlling debugging output) can help isolate the problem.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by root on April, 16 2008 using texi2html 1.76.