Next: Search Path Up: File Inclusion

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

     error-->m4:stdin:1: cannot open `none': No such file or directory
     error-->m4:stdin:2: cannot open `': No such file or directory

   The rest of this section assumes that `m4' is invoked with the `-I'
option (Note: Invoking m4.)  pointing to the
`m4-1.4.13/examples' directory shipped as part of the GNU `m4' package.
The file `m4-1.4.13/examples/incl.m4' in the distribution contains the

     $ cat examples/incl.m4
     =>Include file start
     =>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 file start
     =>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

     $ m4 -I examples
     define(`bar', include(`incl.m4'))
     This is `bar':  >>bar<<
     =>This is bar:  >>Include file start
     =>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' (Note: Undivert) on a named file.

automatically generated by info2www