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::dependenciesreports 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 shipsMapResolver(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
Pendingsentinel in the source cache and reported as the full chain (<root> → a → b → a);ImportLimitscaps 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§
- Import
Limits - 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. - Source
Id - Canonical identity of a source, as produced by
SourceResolver::resolve.
Enums§
- Import
Source - A fetched source document, tagged with the front-end that should parse it.
Constants§
- IMPORT_
SPEC_ FIELD - Field name on an
IMPORT_VARIANTplaceholder that carries the literal source specifier. - IMPORT_
VARIANT - Reserved
ParseTree::variantspelling for an unexpanded import placeholder.
Traits§
- Source
Resolver - 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_strover an already-deserializedserde_json::Value.