include

The include command reads another script file at this point, as if its lines stood here.

Syntax

include <file>

file is a path. It is the run of tokens written glued together after include, with no space between them; a %name or [expr] in it is replaced by its value, cut to an integer.

What it does

James reads the named file in place and goes on with the line after include when it ends. The included file may define parameters, open parts and include more files.

When James applies it

By the preprocessor, when it is read. James opens the file then and not before. It is legal in any phase: Control, Part or Merge.

Rules James adds

A relative path resolves against the current working directory, at the moment the include is read, uniformly at every depth. It is not found from the including file’s directory.
Includes nest to 32 levels, and James refuses a file that is already being included. A file that includes itself gets error [E0202]: include cycle detected: 'self.tg' is already being included.
A computed name is allowed: include part[%n].inc reads part2.inc when %n is 2.
An include inside an if branch that is not taken never opens its file, so a missing file there is no error.
An if, for, when or while opened in an included file must close in that file.

Diagnostics

E0200: the file is not found or cannot be read.
E0201: the nesting is deeper than 32 files.
E0202: the file is already being included.

Example

The script tests/corpus/131-include-nested-provenance/input.tg, which make test runs:

include outer.inc
write

The script includes outer.inc, which includes inner.inc. The prep dump shows only the lines of the files, merge, neutral and stp 0.001, and then write from the script. The note James prints about the tolerance cites inner.inc:1:1, the file that holds it.