Preprocessor
Include Directive
#include "<path>"
#include < <path> >
The #include
directive inserts the contents of another file. The included file is referenced by its path. Typically, it is used to “import” commonly used code like e.g. libraries. Its behavior is similar to the C
-Preprocessor.
Example:
In the following example file a.nc
includes file b.nc
. On execution of a.nc
the interpreter internally replaces the include-line by the text of b.nc
. Therefore, executing the program a.nc
has the same effect as executing the program c.nc
.
FILE a.nc:
G01 X0 Y0 F6000
#include "b.nc"
G01 X0 Y100
FILE b.nc:
G01 Z-2
G01 X100
G01 Z2
FILE c.nc:
G01 X0 Y0 F6000
G01 Z-2
G01 X100
G01 Z2
G01 X0 Y100
- If
path
is absolute, it is directly used to locate the included file. An absolute path must be surrounded by quotation marks. - If
path
is relative and surrounded by quotation marks, it is appended to the directory of the including file to form the path of the included file. - If
path
is enclosed in angle brackets, it is regarded to be relative to the paths in thesearchpath
list. The first entry in this list that leads to an existing file is used for inclusion. Thesearchpath
list is supplied by the interpreter environment of the interpreter.
Example:
The following example assumes that the searchpath
is set to the directories c:\jjj
and c:\kkk
. The file aaa.nc
consists of a sequence of #include
-directives that are explained in the following.
- The file
bbb.nc
is included using an absolute path. Therefore, its location is independent of the location ofaaa.nc
. Absolute referencing is useful for files that always reside at a fixed location on the filesystem. - The file
ccc.nc
is referenced relative. It must reside in the directory ofaaa.nc
(the including file), which isc:\mmm\
. - The file
ddd.nc
is also referenced relative. It is expected to reside atc:\mmm\ooo\ddd.nc
. - The relative reference of
eee.nc
uses the sequence'..'
, which refers to the parent directory. Therefore, the fileeee.nc
is expected inc:\ppp\qqq\eee.nc
. - The relative path of
fff.nc
is denoted in angle brackets. Therefore, the directories in thesearchpath
are considered, rather than the directory ofaaa.nc
. The file is expected inc:\jjj\fff.nc
orc:\kkk\fff.nc
. The first path that leads to an existing file is considered. If there is no filefff.nc
in any directory of thesearchpath
, an error is reported. - Finally, the file
ggg.nc
is expected inc:\rrr\ggg.nc
. Both entries in thesearchpath
lead to this location.
FILE c:\mmm\aaa.nc:
#include "c:\nnn\bbb.nc"
#include "ccc.nc"
#include "ooo\ddd.nc"
#include "..\ppp\qqq\eee.nc"
#include <fff.nc>
#include <../rrr/ggg.nc>
- Each include-directive must be denoted on a dedicated line. Then, this entire line is replaced by the contents of the included file. An additional ‘newline’ character is appended.
- The include-directive may be used multiple times at arbitrary locations of the including file.
- If an included file does not exist, an error is reported.
- If the include directive is not placed at the first position of a line, an error is reported.
- Include directives in included files are also subject to replacement.
- An infinite loop due to recursive inclusion (e.g.
A
includesB
,B
includesC
andC
includesA
) is detected and reported as an error. - The same file may be included multiple times.
It is typically bad practice to include a file multiple times. Especially, if this feature is misused to factor out code. Instead, a function should be preferred to define code that is reused multiple times (see section Userdefined Functions). |
Example:
In the following example file a.nc
includes file b.nc
twice. The second inclusion is always expanded, independently of the enclosing condition by the IF
-THEN
expression. The included file b.nc
itself includes file c.nc
.
FILE a.nc:
G01 X100 F6000
#include "b.nc"
G01 Y100
! IF stVariable=47 THEN
#include "b.nc"
! END_IF;
FILE b.nc:
#include "c.nc"
G01 X0 Y0
FILE c.nc:
G01 Z0
Example:
File x.nc
demonstrates a series of invalid include directives. The first three lines violate the rule that each include directive must be denoted on a dedicated line. In lines 4 and 5 the filename is not properly enclosed in quotation marks or angle brackets. In line 6 a nonexisting file is included. Line 7 violates the rule that the include directive always has to be placed at the first position of a line. Line 8 includes the file y.nc
, which itself includes file x.nc
. This loop is reported as an error.
FILE x.nc:
#include "a.nc" G01 X100
! #include "a.nc"
#include "a.nc" #include "b.nc"
#include a.nc
#include "a.nc>
#include "non_existing_file.nc"
#include "a.nc"
#include y.nc
FILE y.nc:
#include "x.nc"