Info Catalog m4: File Inclusion m4: Search Path

m4: Include

 
 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 (⇒Invoking m4 Preprocessor features.) pointing to the
 'm4-1.4.18/examples' directory shipped as part of the GNU 'm4' package.
 The file 'm4-1.4.18/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' (⇒Undivert) on a named file.
 

Info Catalog m4: File Inclusion m4: Search Path