GNU Info

(m4.info)Include

---

Next: Search Path Prev: File Inclusion Up: File Inclusion

---

Enter node , (file) or (file)node

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.