Skip to main content

Module import

Module import 

Source
Expand description

Load/link phase: expands $import placeholders into a single fully-linked ParseTree before conformance and DslBuild.

§Model

Imports are resolved in a separate load phase, not as a runtime effect: the engine never sees an import, and the existing suspend/resume Call surface keeps meaning “domain effect”, never “go read a file”. The loader walks the import graph to a fixpoint and hands downstream consumers one linked tree — the same resolution-before-evaluation split Bazel’s load() and Dhall’s import judgment standardise.

Three properties carry the design:

  • Literal-only specifiers. An import site names its source with a literal string ({"$import": "lib"} in the JSON front-end), so the full document graph is derivable by a pure syntactic pass — Loaded::dependencies reports it without executing anything.
  • The host owns all IO. The loader itself never touches the filesystem; every byte enters through a caller-supplied SourceResolver. The kit ships MapResolver (named in-memory sources) as the canonical sandboxed implementation; a filesystem resolver is just another impl a host may write.
  • Bounded expansion. Cycles are detected with a Pending sentinel in the source cache and reported as the full chain (<root> → a → b → a); ImportLimits caps depth, source count, and total fetched bytes so reference-expansion blowups fail loudly instead of exhausting memory.

§Placeholder shape

Front-ends represent an import site as a ParseTree whose variant is IMPORT_VARIANT ("$import") carrying a single IMPORT_SPEC_FIELD ("spec") payload. The JSON bridge produces it from {"$import": "name"} at any node position; the canonical text front-end spells the same placeholder @import "name" once add_import_syntax has been applied to the grammar. The loader replaces each placeholder with the parsed-and-expanded tree of the resolved source; placeholders never survive into conformance — a leftover one is a import_codes::UNEXPANDED diagnostic there.

Sharing is by value: two sites importing the same source each receive a clone of the expanded tree. Node identity is minted later (by DslBuild via IdGen), so clones cannot collide.

§Front-ends and mixing

A fetched source declares its front-end via ImportSource: Json parses through serde_bridge::from_json_str, Text through the Loader’s configured Grammar. The two mix freely — a text root may import JSON sources and vice versa — because both land in the same ParseTree trunk before splicing. A Text source arriving at a Loader with no grammar is a loud import_codes::TEXT_UNSUPPORTED failure, not a fallback.

One known limitation: ParseTree::spans inside an expanded tree are byte offsets relative to the source that parsed that subtree, and the tree does not record which source that is. Loader diagnostics carry the resolution chain instead; per-subtree source attribution is a planned follow-up.

§Example

ⓘ
use dsl_kit_parse::import::{ImportLimits, MapResolver, load_json_str};

let mut resolver = MapResolver::new();
resolver.insert("lib", r#"{ "type": "Leaf", "value": "shared" }"#);
let root = r#"{ "type": "Seq", "items": [ { "$import": "lib" } ] }"#;
let loaded = load_json_str(root, &Cfg::schema(), &mut resolver, &ImportLimits::default())?;
assert_eq!(loaded.dependencies.len(), 1);

Modules§

import_codes
Diagnostic codes emitted by the import loader (and the shared placeholder machinery in the front-ends / conformance).

Structs§

ImportLimits
Hard caps on import expansion.
Loaded
A fully-linked document plus its resolved import graph.
Loader
Import loader: a schema, an optional text Grammar, and the expansion limits, bundled so every front-end entry point shares one configuration.
MapResolver
The canonical sandboxed SourceResolver: a map of named in-memory sources.
SourceId
Canonical identity of a source, as produced by SourceResolver::resolve.

Enums§

ImportSource
A fetched source document, tagged with the front-end that should parse it.

Constants§

IMPORT_SPEC_FIELD
Field name on an IMPORT_VARIANT placeholder that carries the literal source specifier.
IMPORT_VARIANT
Reserved ParseTree::variant spelling for an unexpanded import placeholder.

Traits§

SourceResolver
Host-supplied import IO: turns literal specifiers into canonical ids and canonical ids into source text.

Functions§

add_import_syntax
Adds the reserved @import "name" spelling to a text grammar.
load_json_str
Loads a JSON root document with default limits and no text front-end. Convenience wrapper over Loader.
load_json_value
load_json_str over an already-deserialized serde_json::Value.