m4: Include

1 
1 9.1 Including named files
1 =========================
1 
1 There are two builtin macros in 'm4' for including files:
1 
1  -- Builtin: include (FILE)
1  -- Builtin: sinclude (FILE)
1      Both macros cause the file named FILE to be read by 'm4'.  When the
1      end of the file is reached, input is resumed from the previous
1      input file.
1 
1      The expansion of 'include' and 'sinclude' is therefore the contents
1      of FILE.
1 
1      If FILE does not exist, is a directory, or cannot otherwise be
1      read, the expansion is void, and 'include' will fail with an error
1      while 'sinclude' is silent.  The empty string counts as a file that
1      does not exist.
1 
1      The macros 'include' and 'sinclude' are recognized only with
1      parameters.
1 
1      include(`none')
1      error->m4:stdin:1: cannot open `none': No such file or directory
1      =>
1      include()
1      error->m4:stdin:2: cannot open `': No such file or directory
1      =>
1      sinclude(`none')
1      =>
1      sinclude()
1      =>
1 
1    The rest of this section assumes that 'm4' is invoked with the '-I'
1 option (⇒Invoking m4 Preprocessor features.) pointing to the
1 'm4-1.4.18/examples' directory shipped as part of the GNU 'm4' package.
1 The file 'm4-1.4.18/examples/incl.m4' in the distribution contains the
1 lines:
1 
1      $ cat examples/incl.m4
1      =>Include file start
1      =>foo
1      =>Include file end
1 
1    Normally file inclusion is used to insert the contents of a file into
1 the input stream.  The contents of the file will be read by 'm4' and
1 macro calls in the file will be expanded:
1 
1      $ m4 -I examples
1      define(`foo', `FOO')
1      =>
1      include(`incl.m4')
1      =>Include file start
1      =>FOO
1      =>Include file end
1      =>
1 
1    The fact that 'include' and 'sinclude' expand to the contents of the
1 file can be used to define macros that operate on entire files.  Here is
1 an example, which defines 'bar' to expand to the contents of 'incl.m4':
1 
1      $ m4 -I examples
1      define(`bar', include(`incl.m4'))
1      =>
1      This is `bar':  >>bar<<
1      =>This is bar:  >>Include file start
1      =>foo
1      =>Include file end
1      =><<
1 
1    This use of 'include' is not trivial, though, as files can contain
1 quotes, commas, and parentheses, which can interfere with the way the
1 'm4' parser works.  GNU 'm4' seamlessly concatenates the file contents
1 with the next character, even if the included file ended in the middle
1 of a comment, string, or macro call.  These conditions are only treated
1 as end of file errors if specified as input files on the command line.
1 
1    In GNU 'm4', an alternative method of reading files is using
1 'undivert' (⇒Undivert) on a named file.
1