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