Previous: , Up: Syntax   [Contents][Index]

3.1.3 Using Preprocessor to Improve the Configuration.

Before parsing, configuration file is preprocessed. This goes in three stages. First, include directives are expanded. An include directive begins with a ‘#’ sign at the beginning of a line, followed by the word ‘include’ or ‘include_once’. Any amount of whitespace is allowed between the ‘#’ and the word. The entire text up to the end of the line is removed and replaced using the following rules:

#include <file>
#include file

The contents of the file file is included. There are three possible use cases.

If file is an absolute file name, the named file is included. An error message will be issued if it does not exist.

If file contains wildcard characters (‘*’, ‘[’, ‘]’ or ‘?’), it is interpreted as shell globbing pattern and all files matching that pattern are included, in lexicographical order. If no matching files are found, the directive is replaced with an empty line.

Otherwise, the form with angle brackets searches for file in the include search path, while the second one looks for it in the current working directory first, and, if not found there, in the include search path. If the file is not found, an error message will be issued.

The include search path is:

  1. Any directories supplied with the -I (--include-directory) command line option. These directories are scanned in the same order as they appear in the command line.
  2. prefix/share/pies/1.5/include
  3. prefix/share/pies/include

where prefix is the installation prefix.

#include_once <file>
#include_once file

Same as #include, except that, if the file has already been included, it will not be included again.

The obtained material is then passed to m4 for preprocessing. For a complete user manual, refer to In this subsection we assume the reader is sufficiently acquainted with m4 macro processor.

The external preprocessor is invoked with -s flag, instructing it to include line synchronization information in its output. This information is then used by the parser to display meaningful diagnostic. An initial set of macro definitions is supplied by the pp-setup file, located in $prefix/share/pies/1.5/include directory.

The default pp-setup file renames all m4 built-in macro names so they all start with the prefix ‘m4_’. This is similar to GNU m4 --prefix-builtin options, but has an advantage that it works with non-GNU m4 implementations as well.

The include path for m4 is set as described above.

Additional preprocessor symbols may be defined and existing definitions cancelled using the following command line options:

-D symbol[=value]

Define symbol sym as having value, or empty, if the value is not given.

-U sym

Undefine symbol sym.

Finally, the m4 output is passed to the configuration parser. When parsing, the following constructs appearing at the beginning of a line are handled specially:

#line num
#line num "file"

This line causes the parser to believe, for purposes of error diagnostics, that the line number of the next source line is given by num and the current input file is named by file. If the latter is absent, the remembered file name does not change.

# num "file"

This is a special form of #line statement, understood for compatibility with the C preprocessor.

Previous: , Up: Syntax   [Contents][Index]