m4: Include
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, is a directory, or cannot otherwise 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 (⇒Invoking m4 Preprocessor features.) pointing to the
'm4-1.4.18/examples' directory shipped as part of the GNU 'm4' package.
The file 'm4-1.4.18/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 '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':
$ 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.
In GNU 'm4', an alternative method of reading files is using
'undivert' (⇒Undivert) on a named file.