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
sinclude is therefore the
contents of file.
If file does not exist, is a directory, or cannot otherwise be
read, the expansion is void,
include will fail with an error while
silent. The empty string counts as a file that does not exist.
sinclude are recognized only with
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.19/examples
directory shipped as part of the GNU
m4 package. The
file m4-1.4.19/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.