Go to the first, previous, next, last section, table of contents.


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 included 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.


Go to the first, previous, next, last section, table of contents.