The official syntax tree behind a code of declarations, for work this package does not cover.

let code = @quote.items("fn a() -> Unit { () }").render()
inspect(code.items() is Some(_), content="true")

Writes the value to a logger, as <code>Show</code> defines it.

The value as a string, as <code>Show</code> defines it.

Parse the template with its holes standing as placeholders, put each fill where its placeholder stands, and give back the result. Refused when a hole is left empty, a fill names no hole, a fill does not fit where it stands, or the template is not MoonBit.

let text = @quote.items("fn $name() -> Unit { () }").render().to_string() catch {
e => e.to_string()
}
inspect(text, content="hole $name was given nothing")

Fill $hole with code.

let t = @quote.items("fn $name() -> Unit { () }").set(
"name",
@quote.ident("answer"),
)
inspect(
t.render().to_string(),
content="///|\nfn answer() -> Unit {\n  ()\n}\n",
)

Fill $hole* with codes, in order.

let code = @quote.expr("[$items*]")
.splice("items", [@quote.int(1), @quote.int(2), @quote.int(3)])
.render()
inspect(code.to_string(), content="[1, 2, 3]")

The boolean given for key.

The values given for key, in order; empty when it was not given.

Whether key was given.

let source = "#app.get(\"/users\", tag=\"users\")\nfn list_users() -> Unit {}"
let impls = @parser.parse_string(source).0
guard impls is @list.More(impl_, tail=@list.Empty) else {
abort("one declaration")
}
guard impl_ is @syntax.TopFuncDef(fun_decl={ attrs, .. }, ..) else {
abort("a function")
}
guard @attr.find(attrs, "app.get") is Some(a) else { abort("annotated") }
let args = @attr.Spec::new("app.get")
.positional("path", Str)
.many("tag", Str)
.bind(a)
inspect(args.has("tag"), content="true")
inspect(args.has("page"), content="false")

The string given for key.

let source = "#app.get(\"/users\", tag=\"users\")\nfn list_users() -> Unit {}"
let impls = @parser.parse_string(source).0
guard impls is @list.More(impl_, tail=@list.Empty) else {
abort("one declaration")
}
guard impl_ is @syntax.TopFuncDef(fun_decl={ attrs, .. }, ..) else {
abort("a function")
}
guard @attr.find(attrs, "app.get") is Some(a) else { abort("annotated") }
let args = @attr.Spec::new("app.get")
.positional("path", Str)
.many("tag", Str)
.bind(a)
inspect(args.str("path").unwrap_or(""), content="/users")

Every string given for a repeated key.

let source = "#app.get(\"/users\", tag=\"users\")\nfn list_users() -> Unit {}"
let impls = @parser.parse_string(source).0
guard impls is @list.More(impl_, tail=@list.Empty) else {
abort("one declaration")
}
guard impl_ is @syntax.TopFuncDef(fun_decl={ attrs, .. }, ..) else {
abort("a function")
}
guard @attr.find(attrs, "app.get") is Some(a) else { abort("annotated") }
let args = @attr.Spec::new("app.get")
.positional("path", Str)
.many("tag", Str)
.bind(a)
inspect(args.strs("tag").join(", "), content="users")

Whether two values are equal, as <code>Eq</code> defines it.

Whether two values differ, as <code>Eq</code> defines it.

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

The annotation's arguments, checked against the spec.

let source = "#app.get(\"/users\", tag=\"users\")\nfn list_users() -> Unit {}"
let impls = @parser.parse_string(source).0
guard impls is @list.More(impl_, tail=@list.Empty) else {
abort("one declaration")
}
guard impl_ is @syntax.TopFuncDef(fun_decl={ attrs, .. }, ..) else {
abort("a function")
}
guard @attr.find(attrs, "app.get") is Some(a) else { abort("annotated") }
let spec = @attr.Spec::new("app.get").positional("path", Str).many("tag", Str)
let args = spec.bind(a)
inspect(args.str("path").unwrap_or(""), content="/users")
inspect(args.strs("tag").join(", "), content="users")

Pass the file the annotation was read from and every refusal names it, so the line and column in the message can be opened:

let source = "#app.get\nfn list_users() -> Unit {}"
let impls = @parser.parse_string(source).0
guard impls is @list.More(impl_, tail=@list.Empty) else {
abort("one declaration")
}
guard impl_ is @syntax.TopFuncDef(fun_decl={ attrs, .. }, ..) else {
abort("a function")
}
guard @attr.find(attrs, "app.get") is Some(a) else { abort("annotated") }
let refused = try {
let _ = @attr.Spec::new("app.get")
.positional("path", Str)
.bind(a, file="models.mbt")
"bound"
} catch {
e => e.to_string()
}
inspect(refused, content="models.mbt:1:1: path is required")

A parameter that may be given any number of times, tags="a", tags="b", which is how a list is written where the grammar has no arrays. With positional, the list is written as bare arguments, #serde.derive(Serialize, Deserialize), and it takes every one of them from where it starts.

A parameter that may be left out.

A parameter that may be given by position, in the order these are declared, or by name. It is required unless optional says otherwise, which is what lets #orm.table("heroes") and a bare #orm.table both stand.

A required parameter given by name.

Whether two values are equal, as <code>Eq</code> defines it.

Whether two values differ, as <code>Eq</code> defines it.

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

The annotations on a declaration, whatever the view makes of its body.

let source = "#demo.describe\npub struct Point {\n  x : Int\n}"
guard @gen.read("models.mbt", source) is [decl] else {
abort("one declaration")
}
inspect(@attr.find(decl.attrs(), "demo.describe") is Some(_), content="true")

The file the declaration was read from, as read was told it. A refusal a generator writes names this file, so a reader can open the line it points at.

let source = "#demo.describe\npub struct Point {\n  x : Int\n}"
guard @gen.read("src/models.mbt", source) is [decl] else {
abort("one declaration")
}
inspect(decl.file(), content="src/models.mbt")

Whether the declaration is pub, for every kind the view has a variant for and for the tuple structs and traits that land in Other.

The name a declaration introduces: a type's, a function's or a trait's. Empty for one that introduces none, such as an impl. A tuple struct and a trait have no variant of their own, so this is how a generator learns their names without reading raw itself.

let source = "pub struct Rgb(Int, Int, Int)\n\npub fn f() -> Unit { () }"
let names = @gen.read("m.mbt", source).map(decl => decl.name())
inspect(names.join(", "), content="Rgb, f")

The generic parameters of a type declaration, as written: ["A", "B"] for struct Pair[A, B]. Empty for a function, whose own parameters live on Func.

guard @gen.read("m.mbt", "pub struct Pair[A, B] {\n  first : A\n}") is [decl] else {
abort("a struct")
}
inspect(decl.params().join(", "), content="A, B")

What a function says after its return type, as source: empty, raise, raise E or raise? E, so a wrapper can say the same. A type with arguments cannot be an error type, so the name is all there is to print. Empty for anything that is not a function.

guard @gen.read("m.mbt", "fn f() -> Unit raise @a.Bad {}") is [decl] else {
abort("a function")
}
inspect(decl.raises(), content="raise @a.Bad")

The official syntax tree behind the view.

The body of a type declaration, tuple structs included: Struct covers the record case, and this answers the other two. None for a function or a declaration that is not a type at all.

let source = "pub struct Rgb(Int, Int, Int)"
guard @gen.read("m.mbt", source) is [decl] else { abort("a declaration") }
inspect(
match decl.shape() {
Some(Tuple(arity~)) => "tuple of \{arity}"
_ => "not a tuple struct"
},
content="tuple of 3",
)

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

A parameter as a wrapper's signature declares it: a : Int, a~ : Int, a? : Int. A parameter with a default comes out optional, since the default itself stays with the function being wrapped. None when it has no name or no type, so there is nothing to pass along.

guard @gen.read(
"m.mbt", "fn f(a : Int, b~ : String, c~ : Bool = true) -> Unit {}",
)
is [Func(params~, ..)] else {
abort("a function")
}
inspect(
params.map(p => p.declared().unwrap_or("")).join(", "),
content="a : Int, b~ : String, c? : Bool",
)
inspect(
params.map(p => p.passed().unwrap_or("")).join(", "),
content="a, b~, c?",
)

A parameter as a wrapper passes it on: a, a~, a?. None when it has no name.

Whether two values are equal, as <code>Eq</code> defines it.

Whether two values differ, as <code>Eq</code> defines it.

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

The value as a <code>Repr</code>, as <code>Debug</code> defines it.

Every declaration of the inputs, in one call: the code to write for all of them.

Short and stable: it goes in the header of every file it writes.