Skip to content

use-includes.md

Latest commit

 

History

History
74 lines (58 loc) · 2.75 KB

use-includes.md

File metadata and controls

74 lines (58 loc) · 2.75 KB

@use Source Includes

Phase −1.C of docs/archive/bootstrap-plan.html. Lets a Silicon source file pull in other Silicon files at compile time.

Scoped down by ADR-0024 (module/component system, implemented). Inside a project (an sgl.toml-rooted component) @use is no longer needed for intra-component code: all .si files in a module directory are auto-included, and other modules are called as mod::name. A path @use that points at a same-component file is now redundant — it emits a W-USE-REDUNDANT deprecation warning and sgl fix removes it. The bare-name stdlib include (@use 'io';) is retained verbatim — that is the one surviving role at v1.0. Cross-component dependencies use the import line \\ @use name [as alias]; (see ADR-0024). Everything below still describes the underlying concatenation engine, which now also powers stdlib resolution for the component assembler. Standalone files compiled outside a project keep the classic @use-only behaviour described here.

Syntax

@use 'helper.si';
@use './lib/strings.si';
@use '/abs/path/to/file.si';
  • Relative paths resolve from the including file's directory (not the entry's).
  • Absolute paths are honoured as-is.
  • The trailing ; is required (it is the statement terminator the rest of the language uses).
  • Inside a # comment, @use is not followed: # @use 'x.si'; is just a comment.

Semantics

Per the bootstrap plan and cleanup plan, the simplest possible rule:

  1. Textual concatenation in dependency order. Each included file's source is emitted before the includer's. Everything ends up in one global namespace as if the user had concatenated by hand.
  2. Cycle detection. Including A from B and B from A throws a clear error showing the cycle.
  3. Deduplication. The same file referenced multiple times is emitted only once (first sighting wins).
  4. No namespacing yet. Visibility / scoping is deliberately deferred to post-Stage-3. Names from included files appear in the global scope.

Example

# helper.si
\\ add (Int, Int) -> Int
@fn add a, b := { a + b };

# main.si
@use 'helper.si';

sum := { add(1, 2) };

Compiling main.si produces a WAT module that contains $add, $sum, and the top-level add(1, 2) call inside $__start.

Implementation

src/modules/useResolver.ts is a pre-parse text preprocessor. It runs before the parser sees the source so the grammar stays unchanged (per CLAUDE.md). The CLI (src/sigil_cli.ts) calls it before parsing.

Tested by src/modules/useResolver.test.ts (unit) and src/modules/useResolver.integration.test.ts (full pipeline).