dsl block names a grammar that comes from a packageOpen and answer this issue on GitHub.
language, blocked · opened 2026-10-06 · updated 2026-10-07 · 5 comments
Moved from docs/open-decisions.md, which is being retired: open questions for the owner are now issues labelled decision.
What the feature is. A dsl NAME { … } eod block hands its text to a grammar, which parses it while the program is built. A grammar can come from a package: a database driver brings the SQL grammar (ADR-299 D1, Part II 10.5).
Today. ADR-299 D1 says dsl sqlite { … } eod names the grammar of the sqlite package. That works there because the package and the grammar have the same name. Nothing says what a program writes when they differ, for example a package nikaia_sql with a grammar mysql, or a package with two grammars. Part I 9.2 says a name from a package is reached through the package’s name, but the qualified spelling does not parse (probed on 0.0.541):
error: Expected `from` or `{` here, but found `:`.
4 | let q = dsl nikaia_sql::mysql {(An earlier version of Part II 10.5 wrote use nikaia_sql and then dsl mysql; the page now uses sqlite, so the example no longer shows the problem, but the rule is still missing.)
Why it is the owner’s. It is the spelling every program with a DSL from a package writes.
Options
dsl package::grammar, as every other name from a package is written.use brings the grammar’s name in, the one exception to 9.2.Recommendation: 1. It is 9.2’s rule without an exception, and dsl sqlite can remain the short form when package and grammar share a name. Costs if wrong: option 1 wrong means a longer line; option 3 wrong means the exception 9.2 was written to avoid.
To build after the decision: the parser accepts the chosen spelling; ADR-299 D1 and Part II 10.5 state it; a test with a package whose grammar has a different name.
What was checked first: the qualified spelling still does not parse today (error: Expected \from` or `{` here, but found `:` at dsl nikaia_sql::mysql {`).
Options presented:
dsl sqlite would still hold: (a) when the package has one grammar, or (b) only when the grammar is named like the package. The recommendation was (b), since (a) breaks a program the day a package adds a second grammar.Rule: ADR-299 D20, Part II 10.5, NK1228.
package::Grammar: dsl sqlite::Sql(schema: APP) { … } eod.dsl Json.dsl sqlite { … } is NK1228, and the help names the package’s pub grammars.dsl sqlite::Sql. Sql is the example driver’s grammar name; a driver chooses its own.dsl takes a path, NAME (:: NAME)*, before the optional build-time arguments, -> T and {.from-or-{ expectation’s wording for ::.package::Grammar resolves to a pub grammar of a used package.NK1228, with a help listing that package’s pub grammars (dsl sqlite::Sql).grammar Json used as dsl Json { … } eod still works.pub grammar Sql used as dsl pkg::Sql { … } eod works.dsl pkg { … } eod is NK1228, naming pkg::Sql.examples/fortunes.nika’s dsl postgres becomes dsl postgres::Sql.crates/nikaia/tests/refusals.rs and stored_views.rs that write dsl postgres.Generated by Claude Code
Taking the build (session 01DGERcXMpRWbGxPuAFEzp6E).
Generated by Claude Code
dsl takes NAME or NAME::NAME before {. The AST’s Dsl now carries package (ast.nika), and the emitter names the block by its whole path. There are no build-time arguments or -> T on a dsl block yet; those belong to #115 and #114.NK1228: a bare name that a use line brought in, standing where a grammar stands. The message is http is a package, and a dsl block names a grammar., with help Write dsl http::Grammar, naming the grammar http offers.
html (the compiler’s own template) stays bare, and so does a grammar the program declares.examples/fortunes.nika now writes dsl postgres::Sql, and so do refusals.rs and stored_views.rs.dsl_parameters.rs):
dsl http { … } after use http is NK1228;grammar Sql and dsl html stay free of it.What can’t be built yet, and why:
pub grammar, the help that lists them, and a package with two grammars. A package cannot offer a grammar at all today. pub grammar is decided and not built (ADR-296 D25); the parser refuses it with decided and not built. Until it is, dsl pkg::G is checked only as far as the bare form ever was: a statement whose holes the driver binds, or the emitter’s isn’t a language the compiler knows.Part III’s inline-assembly example (30-nikaia-tooling.md, block #13) writes:
use std::backend::x86
…
dsl x86 { … } eodUnder D20, x86 is a module there, so the block is now NK1228. tests/specification/EXPECTED.txt records exactly that change. The example was not rewritten with the sqlite ones.
What is the x86 grammar’s name? dsl x86::Asm, for example. Once a name is chosen the page needs that one line, and the baseline goes back to its old refusal.
I’m leaving the issue open for pub grammar’s half and this question. It stays ready for the first part, which is waiting on ADR-296 D25 being built.
Generated by Claude Code
Decided (owner): dsl x86::Asm.
Part III’s inline-assembly example now writes dsl x86::Asm { … } eod, and ADR-296’s sentence follows (0.0.594). The block in tests/specification/EXPECTED.txt is back to its old refusal, without NK1228.
What remains is build work: a package’s pub grammar (ADR-296 D25), resolution to it, the help listing a package’s grammars, and the two-grammar test. Back to ready.
Generated by Claude Code
Set to blocked on #520. Everything left here (resolution to a package’s pub grammar, the help listing its grammars, the two-grammar test) needs pub grammar, which is decided (ADR-296 D25) and not built. It had no issue of its own until now, so #520 is it. That also makes #485’s remaining steps its step 4.
Generated by Claude Code