Why Aster?
A format like a date, a version number, or a log line usually gets written twice: once as a regex, to validate it, and once as a parser, to read it. The two drift apart. The regex accepts something the parser can't read, or the parser accepts something the schema rejects.
Aster writes both from one grammar. You define the rules once, as named parts built from plain functions rather than regex syntax, and get a regex and a parser that accept exactly the same strings.
A grammar you can read
A regex packs a whole format into one line of punctuation. To check one, you count groups, match parentheses, and notice where the same piece is spelled out again. Aster lets you write the format as named rules instead:
import {
,
,
,
,
,
,
,
,
,
} from "@ghostry/aster";
const { } = ();
const = ()
.("digit", () => ("0", "9"))
.("number", ({ }) =>
(("0"), ([("1", "9"), ()])),
)
.("tag", () => ((("a", "z"), ("0", "9"))))
.("version", ({ , }) =>
([
,
("."),
,
("."),
,
(([("-"), ])),
]),
)
.();
(, "version");
// "^(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)(?:-[0-9a-z]+)?$"number is written once and used three times, where the regex repeats it in full. Escaping, grouping, and quantifiers are Aster's job, so literal(".") becomes \. and nothing turns into a metacharacter by accident. Rules refer to each other by name, and TypeScript checks those names, so a typo is a type error rather than a regex that quietly matches something else. The same names label the parser's nodes. See Defining grammars.
A regex that is safe to ship
A regex is the right tool for a fast yes or no, and sometimes the only one: a JSON Schema pattern, a form field, a database constraint. Aster's patterns are written for that use. They're anchored, have no capturing groups, and mean the same under the u and v flags. See Regex output.
A hand-written regex can also hang. (?:\w+| )* takes exponential time on the wrong input in a backtracking engine, which is what JavaScript and most languages' built-in regex engines are. Aster analyzes every pattern before it returns it, and throws rather than hand back a slow one. See Safe by default.
A parser with the structure kept
A regex with capture groups is a poor parser. A group inside a loop keeps only its last iteration, groups are numbered rather than named by meaning, and nothing is typed.
Aster's parser returns a tree of nodes, one per rule, each with its name, its text, and a source span. Its children are typed from the rule's body: a sequence is a tuple, an either says which alternative matched, and a loop is an array with every iteration in it. See Defining grammars.
The parser runs in time linear in the input for every grammar, so it's safe on input that would make the regex hang. When an input doesn't match, it says where, what could have come next, and the line and column. See Parsing.
Regex semantics, not PEG
Many parser libraries use PEG, where an alternative that matches is final: in "a" / "ab", the input ab takes a and never tries ab. That makes a PEG grammar accept fewer strings than the regex that looks the same.
Aster matches the way a regex does. A string matches when some way of reading it works, so either(literal("a"), literal("ab")) followed by c accepts abc. Order only decides which reading the parser returns when there is more than one, and it returns the one the regex engine would pick.
When not to use it
- Your format nests. Grammars are regular, so a rule can't refer to itself. JSON, arithmetic expressions, and anything with balanced brackets are out of scope for now.
- You only need validation of a simple format. If you never read the structure and the regex is short enough to check by hand, a grammar adds little.
- Parsing is on a hot path. The parser is linear, but it's slower than a native regex: about 90µs for an 84-character log line, against about 0.1µs for the regex test. Validate with the regex, and parse only what you need to read.
