Skip to content

Imports, dictionaries, and program structure

Builtins are implicit; optional library vocabulary is imported explicitly. Resolution uses the selected resource provider and original source ownership, not a search of neighboring files with convenient names.

Released compilers load the embedded English builtins/eng/core.l. The builtin unit owns its canonical definitions and supplies an inherited lexical environment to the program and each imported dictionary. No project bootstrap or lexicon copy is needed; resource overrides are for compiler development.

Bare dictionary names resolve through the selected stdlib/index.json. The current format is version 1, with language keys containing dictionary keys. Each entry names a repository/resource-relative .l entry and the registered Dictionary it exports.

For example:

demo/basic/main.l (lines 1–1)
Use IO's Print from `io` as "Print".

Fragment. Source: demo/basic/main.l (lines 1–1).

Example evidence

Canonical IO.Print import line; the rest of the runnable basic program is omitted. existing-witness-not-run. Evidence guide.

This imports the public member from the registered IO dictionary and binds a local alias. It does not search for a neighboring io directory or io.l, nor does it expose private rendering and writing helpers. Importing the dictionary itself retains a namespace instead of flattening all members into the program.

The index validates duplicate JSON keys, safe resource paths, format, actual entry files, and consistent dictionary identity. An unknown key is an unresolved dictionary; an unsupported provider-style name reports its bounded unsupported-provider diagnostic. There is no package download or unrestricted remote dependency resolver hidden in Use.

Each indexed dictionary owns a private lexical root inheriting builtins. Its public export must resolve to the registered Dictionary. Imported member aliases resolve in that dictionary's environment; helper definitions do not capture caller-added members. Repeated dictionary dependencies reuse canonical dictionary identity while preserving import-site attribution.

A dependency ending in .l is an explicit source include. Program includes resolve relative to the importing source file, even when the compiler is invoked from another CWD. Quoted paths can contain spaces. Included statements retain original spans, physical paragraph identity, and the import occurrence that introduced them.

An include adds occurrences to its importing source unit; it does not automatically create a new public namespace. Imported aliases retain the caller's declaration location while resolving the included target. Interleaved source order survives expansion.

Dictionary-owned includes remain inside that dictionary's resource root and provider. Absolute paths, backslash paths, and traversal escaping that root reject. They cannot fall back to unrelated host files merely because those files exist beside the current process.

Supported example — a project-owned vocabulary and its caller:

The canonical demo/dictionaries/file-import/main.l contains:

demo/dictionaries/file-import/main.l
Use LocalTools's Greeting from `helpers.l` as "Greeting".
Use LocalTools's Display as "Display".
Display Greeting.

Complete program. Source: demo/dictionaries/file-import/main.l.

Example evidence

Project-owned member imports resolved relative to the importing file. existing-witness-not-run. Evidence guide.

The companion helpers.l contains:

demo/dictionaries/file-import/helpers.l
Create "LocalTools" as a Dictionary.
Define LocalTools's "Greeting" as `local hello|`.
Create LocalTools's "Display|-s|-ed|-ing|-er" for Showing any Text.

Fragment. Source: demo/dictionaries/file-import/helpers.l.

Example evidence

Companion vocabulary source for file-import; displayed as a source unit, not independently run. existing-witness-not-run. Evidence guide.

The first import resolves helpers.l beside main.l and aliases Greeting. The second aliases Display from LocalTools. Display Greeting expands to Show and emits local hello| without a newline. Keep both files together.

An include can also occur inside an App-led continuation without discarding its owning paragraph:

testdata/phase1/language/lang-14.l
Use IO's Print from `io` as "Print".
"message" is `imported`.
Create "Worker" as a New Public Basic App.
The App Prints message.
Define "snapshot" as Worker's Output.
Use `continuation.l`.
Show snapshot.
Run Worker.
Show `before-await|`.
Await Worker.
Show `after-await|`.

Complete program. Source: testdata/phase1/language/lang-14.l.

Example evidence

Complete LANG-14 caller includes its sibling continuation.l; existing frontend and native witnesses preserve include order and caller-local snapshot ownership. existing-witness-not-run. Evidence guide.

The included continuation.l supplies:

testdata/phase1/language/continuation.l
"marker" is `from-import|`.
Show snapshot.
Show marker.

Fragment. Source: testdata/phase1/language/continuation.l.

Example evidence

Companion source included by LANG-14; snapshot belongs to the caller and this file is not independently executable. existing-witness-not-run. Evidence guide.

At the include position, snapshot still names the caller's local output snapshot. The included statements show it and marker before the caller's following Show. The files retain separate paragraph identities; a pronoun in the included file cannot borrow an antecedent from the caller. Expected stdout is before-await|imported\nfrom-import|imported\nafter-await|.

Active source/import identity detects cycles and reports the dependency chain. Aliases and descriptor/action expansion have separate cycle checks. Missing files preserve filesystem errors; missing exports are reference/type errors rather than silent empty dictionaries.

Two imports that attempt incompatible declarations in one scope can collide. Case-insensitive bindings and inflections participate in that check. A private helper is not made public by being needed internally by a public export. A member's canonical owner and any private captures remain intact after aliasing.

Intentionally invalid explanatory fragment — a selected import does not expose implementation helpers:

docs/examples/imports-private-helper.l
Use IO's Print from `io` as "Print".
Show Write.

Fragment. Source: docs/examples/imports-private-helper.l.

Example evidence

Intentionally invalid explanatory fragment shortened from the IO02 private-helper regression; Write is unresolved. Static review only, not independently compiled. static-inspection. Evidence guide.

The Print import is valid, but Write is unresolved because it belongs to the dictionary's private lexical root. The distribution test checks this boundary for Write and Discard.

The compiler distinguishes builtin, program, and dictionary source units from individual file occurrences. An explicit include remains in its importing unit and retains source provenance for diagnostics and ownership.

Apps project executable units and their additional constructed Services project libraries. Standalone Service declarations produce no workspace units. Objects are files and Classes are recursive module/source groups; this layout does not introduce runtime lifetimes or lexical paragraph scopes.

App publication retains version-1 manifests. App-constructed library targets have no executable runtime wrapper or start/stop artifacts. Standalone Service declarations create no packages.

The public catalog excludes internal implementation dictionaries. For registry and documentation requirements, see contributing documentation.

Implementations: builder expansion, source units, index validation, lexical roots, member resolution, and index. Existing witnesses: configured imports, case-insensitive imports, collisions, private ownership, dependency capture, and source-unit origins.


Canonical source: docs/spec/imports.md.