5.1.7 Include directives

You may add #include directives in a resource file for searching and loading further resource files⁵⁵. An #include directive tells Gcal to suspend reading the current resource file and read one other resource file before continuing. The directive is a line in the resource file that looks like this template:

#include whitespace argument [whitespace] newline

The argument can either be

"file name"

or⁵⁶

<file name>

One whitespace character minimum is required between #include and the argument. The argument may be trailed by extra whitespace characters and the line must always end with a ‘\n’ (newline) character, except it is the last line of a resource file.

Let us inspect a example which is a bit more concrete:

1. #include "foo/bar"
2. #include <bar>

The first #include directive tells Gcal to load the file bar in the file directory foo from the actual file directory. If this fails, Gcal tries to load this file by using steps 1…4 of the previously explained mechanism used for searching files (see File searching mechanism).

The second #include directive tells Gcal to load the file bar from the user respectively system data file directory by using steps 3…4 of the previously explained mechanism used for searching files. It is not allowed to include files which have a fixed access path starting from the root file directory by such an #include directive like ‘#include </file>’ or ‘#include </foo/bar/file>’; just as the specification of a single or an extended file name containing a disk/drive specifier⁵⁷, because the resulting path name⁵⁸ would not be a valid file name any longer.

Included files may include other files again. But the nesting level of included files is limited on the one hand by the amount of usable working storage of the computer, and on the other hand by the value which is given by the operating system respectively the compiler for the number of files which can be opened simultaneously. Recursive includes⁵⁹ or cyclic includes⁶⁰ are not permitted, because such backward references would produce an infinite loop in the program internally! Gcal recognizes such situations and terminates immediately with a fatal error. See Error Code 119, for more information.

If an included resource file cannot be found and no --debug=abort option is given, processing of the resource file containing the #include continues.