3.2 Preprocessor

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

The contents of the file file is included.

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 named file is included. Unless file is an absolute file name, it will be searched relative to the current working directory. An error message will be issued if it does not exist.

#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 external preprocessor. By default, pies uses GNU m4. This powerful macro processor is described in GNU M4 manual in GNU M4 macro processor. For the rest of this subsection we assume the reader is sufficiently acquainted with the m4 macro processor.

The external preprocessor is invoked with the following two flags: -s flag, instructing it to include line synchronization information in its output, and -P, which changes all m4 built-in macro names by prefixing them with ‘m4_’.

The following command line options are passed to m4 verbatim:

--define=sym[=value]

-D symbol[=value]

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

--undefine=sym

-U sym

Undefine symbol sym.

The --include-directory=dir or -I dir option causes the option -I dir to be appended to the preprocessor command line. This option modifies the m4 include search path (see GNU M4 manual in GNU M4 macro processor).

Finally, the following two options are appended:

-I $prefix/share/pies/include

-I $prefix/share/pies/1.8/include

(where $prefix stands for installation prefix chosen when the package was built. Normally it is /usr.) This step can be disabled using the --no-include option.

These provide the default search path.

The name of the source file is appended to the command line, and the constructed command is executed via $SHELL -c and its output is then 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.

#warning "text"

Emits text as a warning.

#error "text"

Emits text as an error message. Further parsing continues, but will end with failure.

#abend "text"

Emits text as an error message and stops further processing immediately.

If #error or #abend is encountered, the effect is the same as if syntax error has been detected. If it occurs at pies startup, the program will terminate abnormally. If it occurs as part of the reload sequence in a running instance of pies, the configuration file will be rejected and old configuration will remain in effect.