Parsing
toParser(grammar, rule) compiles a rule once and returns a function from a string to a result. Compile once and reuse the function across inputs:
const { toParser } = initialize();
const parse = toParser(date, "date");
parse("2026-11"); // { ok: true, node }
parse("2026-x1"); // { ok: false, span, expected, message }The parser matches whole inputs only, like the anchored regex. To find matches inside a longer string, use the regex with anchored: false.
Linear time, always
The parser runs in time linear in the input for every grammar. It doesn't backtrack, so no input makes it slow, including the inputs that make the grammar's own regex hang. It's the safe way to read untrusted input, whatever the analysis says about the regex.
Linear isn't free: the parser is slower than a native regex test. Validate with the regex where a yes or no is enough, and parse where you need the structure.
Results
A failed parse is a value, never an exception. Check ok first:
const result = parse(input);
if (result.ok) {
result.node; // the rule's Node
} else {
result.message; // for a person
result.expected; // for code
}result.node is the root rule's node, with its rule, text, span, and children.
Failures
A failure is reported at the furthest point any reading of the input reached:
import { , , , , } from "@ghostry/aster";
const { } = ();
const = ()
.("digit", () => ("0", "9"))
.("year", ({ }) => ([, , , ]))
.("month", ({ }) => ([, ]))
.("date", ({ , }) => ([, ("-"), ]))
.();
const = (, "date")("2026-x1");
if (!.) {
.; // 'Expected month at 1:6, found "x".'
.; // [{ kind: "rule", rule: "month" }]
.; // { start: 5, end: 6 }
}spanstarts at the offset where the parse failed and covers the code point found there. At the end of the input it's empty.expectedlists what could have come next there, in the order the grammar prefers them, without duplicates.messagesays the same thing for a person, with a 1-based line and column.
Each entry in expected is one of:
{ kind: "rule", rule }: a named rule that would have started there. Where several start at once, one inside another, the outermost is reported:month, not thedigitthat begins it.{ kind: "characters", ranges }: characters that could have come next where no named rule starts, as inclusive[from, to]ranges, merged into one entry.{ kind: "end" }: a complete match was found, but the input continues.
The rule being parsed is never reported. It starts at offset 0 of every input, so it would be the answer to every failure there and say nothing.
parse("2026"); // Expected "-" at 1:5, found end of input.
parse("2026-11-"); // Expected end of input at 1:8, found "-".Name the rules a reader would recognize. A failure inside an anonymous part lists characters, and one at the start of a named rule names it.
Spans and positions
A span's start and end are UTF-16 offsets, the same ones String.prototype.slice uses, so input.slice(span.start, span.end) is the matched text. end is exclusive.
span.position() gives both ends as lines and columns:
month.span.position();
// { start: { line: 1, column: 6 }, end: { line: 1, column: 8 } }- Lines and columns are 1-based.
- A line ends at
\n,\r\n, or\r. - Columns count code points, so
😀, which is two UTF-16 units, is one column. - Like the offset,
endis just past the last code point, so a span that ends with a line break ends at column 1 of the next line.
Positions are computed only when you ask for them, so a parse that never calls position() doesn't pay for the line index.
