🥮 mooncakes.io

dslx

DSL generation meta-framework for MoonBit

dsl
parser
codegen
moonbit
moon add f4ah6o/dslx@0.1.2
Download zip
Author
Version
0.1.2
License
Apache-2.0
Repository
Last updated
2 months ago
Downloads
42

Dependencies

README

#DSLX

dslx.mbt is a MoonBit meta-framework for describing DSLs with one compact builder surface. It keeps public API names to four characters so coding agents can generate calls consistently.

///|
test {
  let spec = @dslx.dslx("sql")
    .node(
      @dslx.node("Expr").case(
        @dslx.case("Lit").fldx(@dslx.fldx("text", "String")),
      ),
    )
    .rule(
      @dslx.rule("expr").body(@dslx.altx([@dslx.tokn("name"), @dslx.litx("*")])),
    )
    .rule(
      @dslx.rule("decl").body(
        @dslx.seqx([@dslx.litx("let"), @dslx.refx("expr")]),
      ),
    )
  inspect(@dslx.name(spec), content="sql")
  inspect(@dslx.mods(@dslx.emit(spec)).length(), content="4")
  let parsed = @dslx.runx(spec, "decl", "let user")
  inspect(parsed.done, content="true")
  inspect(parsed.posx, content="8")
  match parsed.tree {
    Some(tree) => inspect(tree.kids[1].kind, content="refx:expr")
    None => inspect("none", content="tree")
  }
}

MoonBit uses test as syntax, so the test DSL entrypoint is exported as tstx.

Proj is the small project layer for grouping related specs, examples, and extra virtual files. pack is deterministic and only returns virtual files; it never writes to disk.

///|
test {
  let prj = @dslx.proj("family")
    .file(@dslx.file("README.md", "# family\n"))
    .exmp(@dslx.file("examples/fwd.dsl", "schema User id:int\n"))
    .dslx(@dslx.fwds())
    .dslx(@dslx.wflw())
  let files = @dslx.pack(prj)
  inspect(files[0].path, content="README.md")
  inspect(files[1].path, content="examples/fwd.dsl")
  inspect(files[2].path, content="Fwd/astx.mbt")
  inspect(@dslx.vprj(prj).length(), content="0")
}

fspc, runp, and chex make the project layer useful without unpacking the dslx array manually. runp routes parsing through the named spec and rule. chex checks an example file and returns parser diagnostics only when it fails.

///|
test {
  let file = @dslx.file("examples/fwd.dsl", "schema User id:int\n")
  let prj = @dslx.proj("family").exmp(file).dslx(@dslx.fwds())
  inspect(@dslx.fspc(prj, "Fwd") is Some(_), content="true")
  inspect(@dslx.runp(prj, "Fwd", "sche", file.text).done, content="true")
  inspect(@dslx.chex(prj, "Fwd", "sche", file).length(), content="0")
  inspect(
    @dslx.runp(prj, "Missing", "sche", file.text).digs[0].text,
    content="unknown project spec",
  )
}

#Public API

The main objects are Dslx, Spec, Proj, Node, Rule, Tree, and Diag. The public traits are Pars, Vald, Prnt, and Emit.

The builder surface includes:

  • core: dslx, spec, proj, name
  • AST: node, case, fldx, tree, span
  • grammar: rule, body, seqx, altx, many, optx, litx, tokn, rgxx, refx
  • Pratt parser: prat, pref, infx, post, atom
  • parser: pars, runx, runp
  • validation and diagnostics: vald, vspc, chec, warn, fail, hint, diag
  • printing: prnt, grup, line, join, nest, brkx
  • codegen: emit, file, mods, path
  • project: pack, vprj, fspc, chex, methods dslx, exmp, file
  • examples: fwds, wflw, domn, n8nx, rout, parm, bind, sqlx, slct, from, wher, ordr, limt, html, elem, attr, text, chid, mach, stat, tran, evnt, method init, tstx, givn, when

The code generator returns virtual files only. It does not write to disk.

#Core v1 Contracts

Pout is the parser result. done is true only when parsing succeeded and all non-whitespace input was consumed, tree contains the parse tree on success, posx is the final byte offset after trailing whitespace is skipped, and digs contains diagnostics.

pars(expr, text) parses a single expression tree. It does not resolve refx, so named rule references should be executed through runx(spec, rule, text). pars is strict: it skips whitespace before tokens and expressions, accepts trailing whitespace, and fails if any non-whitespace input remains after a successful expression parse. Leftover input returns done=false, tree=None, and a fail("unexpected input") diagnostic whose span is span("", leftover_pos, leftover_pos).

runx looks up the start rule by name, then resolves refx("name") against the spec rules. It uses the same strict final-consumption rule as pars. Missing start rules or missing references produce fail diagnostics with spans. Successful refx parses keep a wrapper tree named refx:<name> around the referenced rule tree.

Generated pars.mbt rule functions rebuild a private generated spec and call runx(generated_spec(), "<rule>", text). This means generated parser entrypoints resolve refx exactly like hand-written runx calls while still returning virtual files only.

rgxx intentionally supports only explicit scanner patterns in Core v1: [0-9]+ and [a-zA-Z_][a-zA-Z0-9_]*. Unsupported patterns fail validation and fail parsing instead of being treated as literal prefixes.

Parse diagnostics include span information for literal, token, rgxx, refx, start-rule, and refx cycle failures. When there is no wider source range, the parser uses a zero-width span at the current byte offset.

Parser combinator diagnostics are conservative: altx discards failed earlier branches once a later branch succeeds, many stops on the first failed child parse without surfacing that child diagnostic, and optx succeeds with an empty tree when its child fails.

vspc validates empty names, generated-name readiness, duplicate node/case/field/rule names, undefined refx, unsupported rgxx, and empty seqx/altx. Generated-name readiness rejects spec, node, case, field, and rule names that are not MoonBit identifiers: the first byte must be an ASCII letter or _, later bytes must be ASCII letters, digits, or _, and reserved words are not accepted. Diagnostics remain Diag values with kind set to fail or warn plus short hints where useful.

pack(proj) keeps file order stable: explicit project files, example files, then generated files for each Dslx in insertion order. Generated files are namespaced as <SpecName>/astx.mbt, <SpecName>/pars.mbt, <SpecName>/vald.mbt, and <SpecName>/prnt.mbt, which lets multiple DSL specs coexist in one virtual project package. vprj combines spec validation with duplicate spec-name and duplicate virtual-path diagnostics.

fspc(proj, name) returns the matching Dslx by spec name. runp(proj, spec, rule, text) is the project-level parser entrypoint; it returns the same Pout as runx when the spec exists and returns fail("unknown project spec") when it does not. chex(proj, spec, rule, file) parses file.text through runp and returns an empty diagnostic array for successful examples.

#
Emit

source
pub trait Emit {
  fn emit(Self) -> Array[File]
}

#
Pars

source
pub trait Pars {
  fn pars(Self, String) -> Pout
}

#
Prnt

source
pub trait Prnt {
  fn prnt(Self) -> Docx
}

#
Vald

source
pub trait Vald {
  fn vald(Self, Tree) -> Array[Diag]
}

#
Case

source
pub(all) struct Case {
  name : String
  flds : Array[Fldx]
} derive(Eq, 
Debug)

#
Case::fldx

source
fn Case::fldx(self : Case, fld : Fldx) -> Case

#
Diag

source
pub(all) struct Diag {
  kind : String
  text : String
  span : Span?
  hint : String?
} derive(Eq, 
Debug)

#
Diag::hint

source
fn Diag::hint(self : Diag, hint : String) -> Diag

#
Diag::span

source
fn Diag::span(self : Diag, span : Span) -> Diag

#
Docx

source
pub(all) enum Docx {
  Text(String)
  Line
  Join(Array[Docx])
  Grup(Docx)
  Nest(Int, Docx)
  Brkx
} derive(Eq, 
Debug)

#
Dslx

source
pub(all) struct Dslx {
  spec : Spec
} derive(Eq, 
Debug)

#
Dslx::diag

source
fn Dslx::diag(self : Dslx, item : Diag) -> Dslx

#
Dslx::emit

source
fn Dslx::emit(self : Dslx) -> Emix

#
Dslx::node

source
fn Dslx::node(self : Dslx, item : Node) -> Dslx

#
Dslx::rule

source
fn Dslx::rule(self : Dslx, item : Rule) -> Dslx

#
Emix

source
pub(all) struct Emix {
  spec : Spec
  mods : Array[File]
} derive(Eq, 
Debug)

#
Expr

source
pub(all) enum Expr {
  Seqx(Array[Expr])
  Altx(Array[Expr])
  Many(Expr)
  Optx(Expr)
  Litx(String)
  Tokn(String)
  Rgxx(String)
  Refx(String)
  Atom
} derive(Eq, 
Debug)

#
File

source
pub(all) struct File {
  path : String
  text : String
} derive(Eq, 
Debug)

#
Fldx

source
pub(all) struct Fldx {
  name : String
  typx : String
} derive(Eq, 
Debug)

#
Html

source
pub(all) struct Html {
  name : String
  atrs : Array[(String, String)]
  text : String?
  chid : Array[Html]
} derive(Eq, 
Debug)

#
Html::attr

source
fn Html::attr(self : Html, name : String, value : String) -> Html

#
Html::chid

source
fn Html::chid(self : Html, item : Html) -> Html

#
Html::elem

source
fn Html::elem(self : Html, name : String) -> Html

#
Html::text

source
fn Html::text(self : Html, value : String) -> Html

#
Mach

source
pub(all) struct Mach {
  stat : Array[String]
  tran : Array[String]
  evnt : Array[String]
  init : String?
} derive(Eq, 
Debug)

#
Mach::evnt

source
fn Mach::evnt(self : Mach, name : String) -> Mach

#
Mach::init

source
fn Mach::init(self : Mach, name : String) -> Mach

#
Mach::stat

source
fn Mach::stat(self : Mach, name : String) -> Mach

#
Mach::tran

source
fn Mach::tran(self : Mach, name : String) -> Mach

#
Node

source
pub(all) struct Node {
  name : String
  casx : Array[Case]
} derive(Eq, 
Debug)

#
Node::case

source
fn Node::case(self : Node, item : Case) -> Node

#
Oper

source
pub(all) struct Oper {
  kind : String
  text : String
  prec : Int
} derive(Eq, 
Debug)

#
Pout

source
pub(all) struct Pout {
  done : Bool
  tree : Tree?
  posx : Int
  digs : Array[Diag]
} derive(Eq, 
Debug)

#
Prat

source
pub(all) struct Prat {
  opsx : Array[Oper]
  atom : Expr
} derive(Eq, 
Debug)

#
Prat::atom

source
fn Prat::atom(self : Prat, expr : Expr) -> Prat

#
Prat::infx

source
fn Prat::infx(self : Prat, text : String, prec : Int) -> Prat

#
Prat::post

source
fn Prat::post(self : Prat, text : String, prec : Int) -> Prat

#
Prat::pref

source
fn Prat::pref(self : Prat, text : String, prec : Int) -> Prat

#
Proj

source
pub(all) struct Proj {
  name : String
  dslx : Array[Dslx]
  exmp : Array[File]
  mods : Array[File]
} derive(Eq, 
Debug)

#
Proj::dslx

source
fn Proj::dslx(self : Proj, item : Dslx) -> Proj

#
Proj::exmp

source
fn Proj::exmp(self : Proj, item : File) -> Proj

#
Proj::file

source
fn Proj::file(self : Proj, item : File) -> Proj

#
Rout

source
pub(all) struct Rout {
  segs : Array[String]
} derive(Eq, 
Debug)

#
Rout::bind

source
fn Rout::bind(self : Rout, name : String) -> Rout

#
Rout::litx

source
fn Rout::litx(self : Rout, text : String) -> Rout

#
Rout::parm

source
fn Rout::parm(self : Rout, name : String) -> Rout

#
Rule

source
pub(all) struct Rule {
  name : String
  expr : Expr
} derive(Eq, 
Debug)

#
Rule::body

source
fn Rule::body(self : Rule, expr : Expr) -> Rule

#
Span

source
pub(all) struct Span {
  file : String
  from : Int
  upto : Int
} derive(Eq, 
Debug)

#
Spec

source
pub(all) struct Spec {
  name : String
  nods : Array[Node]
  ruls : Array[Rule]
  digs : Array[Diag]
} derive(Eq, 
Debug)

#
Sqlx

source
pub(all) struct Sqlx {
  cols : Array[String]
  from : Array[String]
  wher : String?
  join : Array[String]
  grup : Array[String]
  ordr : Array[String]
  limt : Int?
} derive(Eq, 
Debug)

#
Sqlx::from

source
fn Sqlx::from(self : Sqlx, tbls : Array[String]) -> Sqlx

#
Sqlx::grup

source
fn Sqlx::grup(self : Sqlx, col : String) -> Sqlx

#
Sqlx::join

source
fn Sqlx::join(self : Sqlx, tbl : String) -> Sqlx

#
Sqlx::limt

source
fn Sqlx::limt(self : Sqlx, limt : Int) -> Sqlx

#
Sqlx::ordr

source
fn Sqlx::ordr(self : Sqlx, col : String) -> Sqlx

#
Sqlx::slct

source
fn Sqlx::slct(self : Sqlx, cols : Array[String]) -> Sqlx

#
Sqlx::wher

source
fn Sqlx::wher(self : Sqlx, cond : String) -> Sqlx

#
Tree

source
pub(all) struct Tree {
  kind : String
  text : String
  kids : Array[Tree]
  span : Span?
} derive(Eq, 
Debug)

#
Tstx

source
pub(all) struct Tstx {
  name : String
  givn : Array[String]
  when : Array[String]
  chec : Array[String]
} derive(Eq, 
Debug)

#
Tstx::chec

source
fn Tstx::chec(self : Tstx, text : String) -> Tstx

#
Tstx::givn

source
fn Tstx::givn(self : Tstx, text : String) -> Tstx

#
Tstx::when

source
fn Tstx::when(self : Tstx, text : String) -> Tstx

#
Vctx

source
pub(all) struct Vctx {
  tree : Tree
  digs : Array[Diag]
} derive(Eq, 
Debug)

#
Vctx::chec

source
fn Vctx::chec(self : Vctx, ok : Bool, msg : String) -> Vctx

#
Vctx::fail

source
fn Vctx::fail(self : Vctx, msg : String) -> Vctx

#
Vctx::warn

source
fn Vctx::warn(self : Vctx, msg : String) -> Vctx

#
altx

source
fn altx(items : Array[Expr]) -> Expr

#
atom

source
fn atom() -> Expr

#
attr

source
fn attr(name : String, value : String) -> (String, String)

#
bind

source
fn bind(text : String) -> String

#
body

source
fn body(rule : Rule, expr : Expr) -> Rule

#
brkx

source
fn brkx() -> Docx

#
case

source
fn case(name : String) -> Case

#
chec

source
fn chec(v : Vctx, ok : Bool, msg : String) -> Vctx

#
chex

source
fn chex(value : Proj, spec : String, rule : String, file : File) -> Array[Diag]

#
chid

source
fn chid(item : Html) -> Html

#
diag

source
fn diag(kind : String, text : String) -> Diag

#
domn

source
fn domn() -> Dslx

#
dslx

source
fn dslx(name : String) -> Dslx

#
elem

source
fn elem(name : String) -> String

#
emit

source
fn emit(value : Dslx) -> Emix

#
evnt

source
fn evnt(name : String) -> String

#
fail

source
fn fail(text : String) -> Diag

#
file

source
fn file(path : String, text : String) -> File

#
fldx

source
fn fldx(name : String, typx : String) -> Fldx

#
from

source
fn from(tbls : Array[String]) -> Array[String]

#
fspc

source
fn fspc(value : Proj, name : String) -> Dslx?

#
fwds

source
fn fwds() -> Dslx

#
givn

source
fn givn(text : String) -> String

#
grup

source
fn grup(doc : Docx) -> Docx

#
hint

source
fn hint(text : String) -> String

#
html

source
fn html() -> Html

#
join

source
fn join(items : Array[Docx]) -> Docx

#
limt

source
fn limt(n : Int) -> Int

#
line

source
fn line() -> Docx

#
litx

source
fn litx(text : String) -> Expr

#
mach

source
fn mach() -> Mach

#
many

source
fn many(item : Expr) -> Expr

#
mods

source
fn mods(value : Emix) -> Array[File]

#
n8nx

source
fn n8nx() -> Dslx

#
name

source
fn name(value : Dslx) -> String

#
nest

source
fn nest(size : Int, doc : Docx) -> Docx

#
node

source
fn node(name : String) -> Node

#
optx

source
fn optx(item : Expr) -> Expr

#
ordr

source
fn ordr(col : String) -> String

#
pack

source
fn pack(value : Proj) -> Array[File]

#
parm

source
fn parm(text : String) -> String

#
pars

source
fn pars(expr : Expr, text : String) -> Pout

#
path

source
fn path(text : String) -> String

#
prat

source
fn prat() -> Prat

#
prnt

source
fn prnt(doc : Docx) -> String

#
proj

source
fn proj(name : String) -> Proj

#
refx

source
fn refx(text : String) -> Expr

#
rgxx

source
fn rgxx(text : String) -> Expr

#
rout

source
fn rout() -> Rout

#
rule

source
fn rule(name : String) -> Rule

#
runp

source
fn runp(value : Proj, spec : String, rule : String, text : String) -> Pout

#
runx

source
fn runx(spec : Dslx, rule : String, text : String) -> Pout

#
seqx

source
fn seqx(items : Array[Expr]) -> Expr

#
slct

source
fn slct(cols : Array[String]) -> Array[String]

#
span

source
fn span(file : String, from : Int, upto : Int) -> Span

#
spec

source
fn spec(name : String) -> Spec

#
sqlx

source
fn sqlx() -> Sqlx

#
stat

source
fn stat(name : String) -> String

#
text

source
fn text(value : String) -> Docx

#
tokn

source
fn tokn(text : String) -> Expr

#
tran

source
fn tran(name : String) -> String

#
tree

source
fn tree(kind : String, text : String, kids? : Array[Tree], span? : Span) -> Tree

#
tstx

source
fn tstx(name : String) -> Tstx

#
vald

source
fn vald(tree : Tree) -> Vctx

#
vprj

source
fn vprj(value : Proj) -> Array[Diag]

#
vspc

source
fn vspc(value : Dslx) -> Array[Diag]

#
warn

source
fn warn(text : String) -> Diag

#
wflw

source
fn wflw() -> Dslx

#
when

source
fn when(text : String) -> String

#
wher

source
fn wher(cond : String) -> String

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io