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 the searchpath list. The first entry in this list that leads to an existing file is used for inclusion. The searchpath 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 of aaa.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 of aaa.nc (the including file), which is c:\mmm\.
• The file ddd.nc is also referenced relative. It is expected to reside at c:\mmm\ooo\ddd.nc.
• The relative reference of eee.nc uses the sequence '..', which refers to the parent directory. Therefore, the file eee.nc is expected in c:\ppp\qqq\eee.nc.
• The relative path of fff.nc is denoted in angle brackets. Therefore, the directories in the searchpath are considered, rather than the directory of aaa.nc. The file is expected in c:\jjj\fff.nc or c:\kkk\fff.nc. The first path that leads to an existing file is considered. If there is no file fff.nc in any directory of the searchpath, an error is reported.
• Finally, the file ggg.nc is expected in c:\rrr\ggg.nc. Both entries in the searchpath 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 includes B, B includes C and C includes A) 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"