Language Reference
include
A compile-time source directive for incorporating another Raz source file.
Purpose
The include directive incorporates another Raz source
file into the input being compiled. It supports file-level
organization and reuse without defining a standard-library function
or performing runtime file loading.
Syntax
include "path/to/file.raz";
include("path/to/file.raz");The current scanner requires a double-quoted string path. The terminating semicolon is optional where the directive scanner accepts the following source boundary.
Example
math.raz
function square(value: i64) -> i64 {
return value * value;
}main.raz
include "math.raz";
function main() -> i64 {
return square(12);
}
The declaration from math.raz becomes part of the
compilation input before parsing and semantic validation.
Current behavior
| Behavior | Implementation snapshot |
|---|---|
| Expansion stage | Runs during source resolution, before macro expansion, parsing, and semantic analysis. |
| Relative path | Resolved from the directory of the file containing the directive. |
| Normalization |
. and .. path segments are
lexically normalized for identity checks.
|
| Nested inclusion | Included files are processed recursively. |
| Duplicate paths | A normalized path is included at most once per resolution state. |
| Circular paths | Active-path cycles cause compilation to fail with an include diagnostic. |
| Missing/unreadable file | Causes compilation to fail with an include diagnostic. |
| Quoted/commented text | Directive-looking text in string literals and line/block comments is ignored. |
Decisions to finalize
- Whether duplicate suppression is a permanent language rule or an implementation detail.
- Cross-platform path normalization, path case sensitivity, and symlink behavior.
- How diagnostics map to original source locations after expansion.
- Whether empty included files must be accepted; the current implementation treats an empty read result as a read failure.
- The exact grammar for optional semicolons.