There are two builtin macros in
m4 for including files:
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
sincludeis therefore the contents of file.
If file does not exist, is a directory, or cannot otherwise be read, the expansion is void, and
includewill fail with an error while
sincludeis silent. The empty string counts as a file that does not exist.
sincludeare 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 Invoking m4)
pointing to the m4-1.4.16/examples
directory shipped as part of the GNU
m4 package. The
file m4-1.4.16/examples/incl.m4 in the distribution
contains the lines:
$ cat examples/incl.m4 ⇒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:
$ m4 -I examples define(`foo', `FOO') ⇒ include(`incl.m4') ⇒Include file start ⇒FOO ⇒Include file end ⇒
The fact that
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
$ m4 -I examples 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.
m4, an alternative method of reading files is
undivert (see Undivert) on a named file.