8. File inclusion

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

8.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 `examples' directory shipped as part of the GNU m4 package. The file `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.

8.2 Searching for include files

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

If a file is not found in the current working directory, and the file name is not absolute, the file will be looked for in a specified search path. First, the directories specified with the `-I' option will be searched, in the order found on the command line (see section Invoking m4). Second, 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.

This document was generated by System Administrator on September, 23 2007 using texi2html 1.70.