Including named files
=====================
There are two builtin macros in `m4' for including files:
include(FILENAME)
sinclude(FILENAME)
both of which cause the file named FILENAME 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 FILENAME.
It is an error for an `include'd file not to exist. If you do not
want error messages about non-existent files, `sinclude' can be used to
include a file, if it exists, expanding to nothing if it does not.
include(`no-such-file')
=>
error-->30.include:2: m4: Cannot open no-such-file: No such file or directory
sinclude(`no-such-file')
=>
Assume in the following that the file `incl.m4' 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.
The builtin macros `include' and `sinclude' are recognized only when
given arguments.