File: m4.info,  Node: Include,  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
     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 (*note Invoking m4: Preprocessor features.) pointing to the
‘m4-1.4.20/examples’ directory shipped as part of the GNU ‘m4’ package.
The file ‘m4-1.4.20/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’ (*note Undivert::) on a named file.