Repository navigation
Standard Library Structure (@use Directives) #90
Description
Description
Define how NLS ships with built-in semantic domains that users can import.
@use math.core
@use validation.contracts
These are not Python imports — they're semantic building blocks the compiler understands.
Proposed Domains
math.core
- Unit types (length, mass, time, force, etc.)
- Dimensional analysis rules
- Numeric tolerances and comparison
validation.contracts
- Preconditions, postconditions
- Invariant helpers
- Contract composition
system.events
- Logging semantics
- State transition patterns
- Event emission
Acceptance Criteria
-
@usedirective syntax added to grammar - Compiler resolves
@useto bundled.nlfiles - At least one working domain (
math.core) with tests - Documentation for creating custom domains
Open Questions
- Where do stdlib
.nlfiles live? (nlsc/stdlib/?) - How do user-defined domains interact with stdlib?
- Versioning strategy for stdlib changes?
Activity
Mnehmos commentedon Sep 12, 2026
Closing by audit — every acceptance criterion is implemented on master:
@usedirective syntax added to grammarnlsc/parser.pydirective regex includesuse;module.usesinnlsc/schema.py; tree-sitter path handles@usevianlsc/parser_treesitter.py(_sanitize_source_for_treesitter+ regex canonical path)@useto bundled.nlfilesnlsc/stdlib_resolver.py(resolve_use, root precedence: project.nls/stdlib>--stdlib-path>NLS_STDLIB_PATH> bundlednlsc/stdlib), wired into compile/verify/run/watch vianlsc/pipeline.py resolve_stdlib_usesmath.core) with testsnlsc/stdlib/MANIFEST.json+nlsc/stdlib/v1/math/core.nl; 7 end-to-end tests intests/test_issue_90_use_directives.py(bundled resolution, auto parser,EUSE001on compile and verify, project-local override, CLI > env > bundled precedence)docs/language-spec.md@usesection,docs/cli-reference.md(--stdlib-path, override roots),docs/error-reference.md(EUSE001),docs/design/issue-90-use-directives.md(custom domain layout)One scoped caveat, recorded for the record: resolution is metadata-only — resolved stdlib ANLUs are not linked into the emitted program. That was an explicit non-goal of the implemented slice (
docs/design/issue-90-use-directives.md, "type checking / export syntax is out of Slice C") and is not in this issue's acceptance criteria; symbol linking across modules belongs to the package model in #146. Also onlymath.coreof the three proposed domains was built — the criterion required "at least one".