(m4.info.gz) Include

Info Catalog

(m4.info.gz) File Inclusion

(m4.info.gz) Search Path

 
 8.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 (or cannot 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) pointing to the `examples' directory
 shipped as part of the GNU `m4' package.  The file `examples/incl.m4'
 in the distribution 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.  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.
 

Info Catalog

(m4.info.gz) File Inclusion

(m4.info.gz) Search Path