Public API
The package has two entry points:
@ghostry/aster:grammar, the combinators,initialize,AsterError, and the types.@ghostry/aster/unstable-ir: the expression types,Kind, andsubexpressions, for tools that read a grammar's structure. See Grammars as data.
grammar()
function grammar(): GrammarBuilder;
interface GrammarBuilder {
define(name: string, build: (rules: Vocabulary) => Expr): GrammarBuilder;
compose(): Grammar;
}Starts a grammar. define adds a rule, and build receives references to every earlier rule, by name. compose finishes the grammar. Builders are immutable: define returns a new one. See Defining grammars.
define throws one of the definition errors for a rule it can't add.
Combinators
function literal(value: string): Literal;
function range(from: string, to: string): Range;
function sequence(items: readonly Expr[]): Sequence;
function either(...alternatives: [Expr, ...Expr[]]): Either;
function optional(body: Expr): Optional;
function zeroOrMore(body: Expr): Repeat;
function oneOrMore(body: Expr): Repeat;
function repeat(body: Expr, bounds: { min: number; max?: number }): Repeat;Each returns frozen plain data and checks nothing: define checks the body it's given. What each one matches and contributes to a node is in the combinator table.
initialize(config)
function initialize(config?: Config): {
toPattern(grammar: Grammar, rule: string, options?: PatternOptions): string;
toRegExp(grammar: Grammar, rule: string, options?: PatternOptions): RegExp;
toParser(grammar: Grammar, rule: string): Parser;
analyze(grammar: Grammar, rule: string, options?: PatternOptions): Analysis;
};Builds the functions that read a grammar. Each one takes the rule's name, checked against the grammar's rules by TypeScript, and throws UnknownRuleError for a name the grammar doesn't have. A grammar that arrived as data is checked first, as define would.
| function | returns |
|---|---|
toPattern | the rule's pattern source. See Regex output |
toRegExp | toPattern's source, compiled with the v flag |
toParser | a function from a string to a ParseResult. See Parsing |
analyze | how slow the rule's pattern can be in a backtracking engine. See Safe by default |
toPattern and toRegExp throw VulnerablePatternError for a pattern slower than allowedComplexity. analyze never throws for a slow one.
PatternOptions has one field, anchored, which defaults to true. See Anchoring.
Config
Every field is optional. A value a field doesn't accept throws InvalidConfigError, rather than falling back to the default.
| field | default | meaning |
|---|---|---|
allowedComplexity | "linear" | The slowest pattern toPattern and toRegExp return: "linear", "polynomial", or "exponential", which allows everything. |
analysisBudget | 1_000_000 | Steps the analysis may spend on its exact pass before falling back to a finding with exact: false. 0 always falls back, and Infinity never does. |
Results
type ParseResult<Node> =
| { ok: true; node: Node }
| {
ok: false;
span: Span;
expected: readonly Expectation[];
message: string;
};
interface Node<Name, Children> {
rule: Name;
span: Span;
text: string;
children: Children;
}
interface Span {
start: number;
end: number;
position(): { start: Position; end: Position };
}
type Expectation =
| { kind: "rule"; rule: string }
| { kind: "characters"; ranges: readonly (readonly [string, string])[] }
| { kind: "end" };
type Analysis =
| { complexity: "linear" }
| {
complexity: "polynomial";
degree: number;
rule: string;
attack: Attack;
exact: boolean;
}
| { complexity: "exponential"; rule: string; attack: Attack; exact: boolean };
interface Attack {
prefix: string;
pump: string;
suffix: string;
}Every field is readonly. See Failures, Spans and positions, and Analyze without throwing.
Types
| type | what it is |
|---|---|
AstOf<Grammar, Name> | the node a grammar's rule produces |
Ast<Rules, Name> | the same, from a grammar's rule definitions |
Children<Expr, Rules> | what an expression contributes to its rule's node |
Grammar | a composed grammar, { rules } |
GrammarBuilder | what grammar() and define return |
RuleDefinition | one rule, { name, body } |
RuleNames<Grammar> | the names of a grammar's rules |
RuleRef | a reference to a rule, { kind: "reference", name } |
Vocabulary | the object of references a builder receives |
Expr | any expression, the union of the combinators' return types |
Parser<Node> | what toParser returns |
Vulnerability | an Analysis that isn't linear |
The expression types (Literal, Range, Sequence, Either, Optional, Repeat) are exported so that inferred grammar types can be named in your own declarations. They aren't a stable contract for reading a grammar's structure yet.
AsterError
Every error aster throws is a subclass of AsterError, so instanceof AsterError catches them all. Each subclass is on the AsterError namespace, and each one's name is "@ghostry/aster:<Class>", so it can be told apart where instanceof can't, such as across two installed copies of the package. Each message stands on its own, and the fields are there for code that needs them.
| error | thrown by | when | fields |
|---|---|---|---|
AsterError.DuplicateRuleError | define | the name is already defined | rule |
AsterError.UnknownReferenceError | define | the body refers to a rule not defined before it | rule, reference |
AsterError.InvalidRangeError | define | an endpoint isn't one code point, or they're reversed | rule, from, to, reason |
AsterError.InvalidRepetitionError | define | min or max isn't a valid bound | rule, min, max |
AsterError.EmptyEitherError | define | an either has no alternatives | rule |
AsterError.NullableQuantifierError | define | a loop or optional body can match the empty string | rule, combinator |
AsterError.InvalidExpressionError | define | a body contains something that isn't an expression | rule, value |
AsterError.InvalidConfigError | initialize | a config field has a value it doesn't accept | option, value |
AsterError.VulnerablePatternError | toPattern, toRegExp | the pattern is slower than allowedComplexity | rule, analysis |
AsterError.UnknownRuleError | toPattern, toRegExp, toParser, analyze | the grammar has no rule by that name | rule |
reason is "endpoint" or "order", and combinator is "optional" or "repeat". The definition errors are also thrown by the initialize functions for a grammar that arrived as data.
