Grammars as data
A composed grammar is plain, frozen data. It's { rules }, each rule's name and body in definition order, with references held by name:
date.rules[1];
// {
// name: "year",
// body: {
// kind: "sequence",
// items: [
// { kind: "reference", name: "digit" },
// { kind: "reference", name: "digit" },
// { kind: "reference", name: "digit" },
// { kind: "reference", name: "digit" },
// ],
// },
// }That makes a grammar easy to store, send, and generate.
JSON round trips
A grammar survives JSON.stringify and JSON.parse unchanged. An unbounded repeat leaves out max rather than setting it to undefined, so nothing is lost on the way.
toPattern, toRegExp, toParser, and analyze all accept a grammar that arrived as data. They check it the way .define() would, so a malformed grammar throws the same definition errors:
const stored = JSON.parse(JSON.stringify(date));
toPattern(stored, "date"); // "^[0-9][0-9][0-9][0-9]-[0-9][0-9]$"Only the rules up to the one you ask for are read.
A grammar that arrived as data has a wide type, so its AST's children are unknown. Keep the composed grammar's own type where you can, or check the shape yourself.
Analyses are cached only for frozen grammars, which is what .compose() returns. A grammar that arrived as data may be changed later, so it's analyzed every time.
The unstable IR
@ghostry/aster/unstable-ir exports the node types and a helper, for tools that read a grammar's structure, such as a documentation generator or a grammar linter:
- the expression types:
Literal,Range,Sequence,Either,Optional,Repeat,RuleRef, and their unionExpr GrammarandRuleDefinitionKind, the union of everykindsubexpressions(expr), an expression's direct children
import { subexpressions, type Expr } from "@ghostry/aster/unstable-ir";
function count(body: Expr): number {
let total = 0;
const stack = [body];
for (let expr = stack.pop(); expr; expr = stack.pop()) {
total++;
stack.push(...subexpressions(expr));
}
return total;
}Walk a body with a stack, as above, rather than recursion. A body can nest deeper than the call stack.
As the name says, any of it can change in any release until its shape is settled. It will move to a stable path then.
