functionalscript 0.44.0 → 0.46.0

package/fjs/bnf/descent/proof.f.mjs

@@ -2,16 +2,17 @@
  * @module
  *
  * @import { CodePoint } from '../../text/utf16/types.ts'
+ * @import { RuleSet } from '../data/types.ts'
  * @import { DescentMatch, CodePointMeta, DescentMatchResult } from './types.ts'
  */
 
 import { stringToCodePointList } from '../../text/utf16/module.f.mjs'
 import { map, toArray } from '../../types/list/module.f.mjs'
-import { commaJoin0Plus, option, range, repeat0Plus, set } from '../module.f.mjs'
+import { commaJoin0Plus, eof, option, range, repeat0Plus, set } from '../module.f.mjs'
 import { emptyTagMap, toData } from '../data/module.f.mjs'
-import { descentParser } from './module.f.mjs'
+import { descentParser, descentParserRuleSet } from './module.f.mjs'
 import { assertEq, assertNotNullish } from '../../asserts/module.f.mjs'
-import { deterministic } from '../testlib.f.mjs'
+import { deterministic, showAst } from '../testlib.f.mjs'
 
 /** @type {(cp: CodePoint) => CodePointMeta<unknown>} */
 const mapCodePoint = cp => [cp, undefined]
@@ -77,11 +78,14 @@ export const proof = {
             if (result !== '{"0":"none","3":true,"":true,"r":"none"}') { throw result }
         },
         () => {
+            // The whole repetition is one `repeat` rule, and a repetition always
+            // matches empty — with no tag, because it is a list of items rather
+            // than a choice between branches.
             const repeatRule = repeat0Plus(set(' \n\r\t'))
             const data = toData(repeatRule)
             const emptyTags = emptyTagMap(data[0])
             const result = JSON.stringify(emptyTags)
-            if (result !== '{"5":true,"r":"none"}') { throw result }
+            assertEq(result, '{"r":true}')
         }
     ],
     descentParser: [
@@ -254,33 +258,62 @@ export const proof = {
         () => {
             const m = descentParser(deterministic())
 
-            const expect = (/** @type {string} */s, /** @type {boolean} */expected) => {
+            // A match is pinned by the AST it built, not just by the fact that it
+            // matched: the shape is what a repetition changes, and asserting it
+            // subsumes success — only a full match produces one. `showAst` writes
+            // a node as `tag(children)` with the code points it consumed as one
+            // quoted string, `*` for the tagless empty match.
+            //
+            // The leading three spaces are the `repeat` to read first: they are
+            // three siblings of one node here, and three levels of nesting in the
+            // LL(1) backend's copy of these expectations.
+            /** @type {(s: string, expected: string) => void} */
+            const expectAst = (s, expected) => {
                 const cp = toArray(stringToCodePointList(s))
                 const mr = descentParserCpOnly(m, '', cp)
-                const success = mr.success && mr.idx === cp.length
-                assertEq(success, expected, mr)
+                assertEq(mr.success, true, s)
+                assertEq(mr.idx, cp.length, s)
+                assertEq(showAst(mr.ast), expected, s)
+            }
+
+            /** @type {(s: string) => void} */
+            const expectNoMatch = s => {
+                const cp = toArray(stringToCodePointList(s))
+                const mr = descentParserCpOnly(m, '', cp)
+                assertEq(mr.success && mr.idx === cp.length, false, s)
             }
 
-            expect('   true   ', true)
-            expect('   tr2ue   ', false)
-            expect('   true"   ', false)
-            expect('   "Hello"   ', true)
-            expect('   "Hello   ', false)
-            expect('   "Hello\\n\\r\\""   ', true)
-            expect('   -56.7e+5  ', true)
-            expect('   h-56.7e+5   ', false)
-            expect('   -56.7e+5   3', false)
-            expect('   [] ', true)
-            expect('   {} ', true)
-            expect('   [[[]]] ', true)
-            expect('   [1] ', true)
-            expect('   [ 12, false, "a"]  ', true)
-            expect('   [ 12, false2, "a"]  ', false)
-            expect('   { "q": [ 12, false, [{"b" : "c"}], "a"] }  ', true)
-            expect('   { "q": [ 12, false, [{}], "a"] }  ', true)
-            expect('   { "q": [ 12, false, [}], "a"] }  ', false)
-            expect('   [{ "q": [ 12, false, [{}], "a"] }]  ', true)
-            expect('   [{ "q": [ 12, false, [}], "a"] }]  ', false)
+            expectAst('   true   ', '((" "(" ") " "(" ") " "(" ")) "true"(("t") ("r") ("u") ("e")) (" "(" ") " "(" ") " "(" ")))')
+            expectAst('   "Hello"   ', '((" "(" ") " "(" ") " "(" ")) "string"((("\\"")) ("0x2300005b"("H") "0x5d10ffff"("e") "0x5d10ffff"("l") "0x5d10ffff"("l") "0x5d10ffff"("o")) (("\\""))) (" "(" ") " "(" ") " "(" ")))')
+            expectAst('   "Hello\\n\\r\\""   ', '((" "(" ") " "(" ") " "(" ")) "string"((("\\"")) ("0x2300005b"("H") "0x5d10ffff"("e") "0x5d10ffff"("l") "0x5d10ffff"("l") "0x5d10ffff"("o") "escape"((("\\\\")) "n"("n")) "escape"((("\\\\")) "r"("r")) "escape"((("\\\\")) "\\""("\\""))) (("\\""))) (" "(" ") " "(" ") " "(" ")))')
+            expectAst('   -56.7e+5  ', '((" "(" ") " "(" ") " "(" ")) "number"("some"(("-")) "onenine"(("5") (("6"))) "some"(((".")) (("7") ())) "some"("e"("e") "+"("+") (("5") ()))) (" "(" ") " "(" ")))')
+            expectAst('   [] ', '((" "(" ") " "(" ") " "(" ")) "array"((("[")) () "none"() (("]"))) (" "(" ")))')
+            expectAst('   {} ', '((" "(" ") " "(" ") " "(" ")) "object"((("{")) () "none"() (("}"))) (" "(" ")))')
+            expectAst('   [[[]]] ', '((" "(" ") " "(" ") " "(" ")) "array"((("[")) () "some"(("array"((("[")) () "some"(("array"((("[")) () "none"() (("]"))) ()) "none"()) (("]"))) ()) "none"()) (("]"))) (" "(" ")))')
+            expectAst('   [1] ', '((" "(" ") " "(" ") " "(" ")) "array"((("[")) () "some"(("number"("none"() "onenine"(("1") ()) "none"() "none"()) ()) "none"()) (("]"))) (" "(" ")))')
+            expectAst('   [ 12, false, "a"]  ', '((" "(" ") " "(" ") " "(" ")) "array"((("[")) (" "(" ")) "some"(("number"("none"() "onenine"(("1") (("2"))) "none"() "none"()) ()) "some"(((((",")) (" "(" "))) ("false"(("f") ("a") ("l") ("s") ("e")) ())) "some"(((((",")) (" "(" "))) ("string"((("\\"")) ("0x5d10ffff"("a")) (("\\""))) ())) "none"()))) (("]"))) (" "(" ") " "(" ")))')
+            expectAst('   { "q": [ 12, false, [{"b" : "c"}], "a"] }  ', '((" "(" ") " "(" ") " "(" ")) "object"((("{")) (" "(" ")) "some"(((((("\\"")) ("0x5d10ffff"("q")) (("\\""))) () ((":")) (" "(" ")) "array"((("[")) (" "(" ")) "some"(("number"("none"() "onenine"(("1") (("2"))) "none"() "none"()) ()) "some"(((((",")) (" "(" "))) ("false"(("f") ("a") ("l") ("s") ("e")) ())) "some"(((((",")) (" "(" "))) ("array"((("[")) () "some"(("object"((("{")) () "some"(((((("\\"")) ("0x5d10ffff"("b")) (("\\""))) (" "(" ")) ((":")) (" "(" ")) "string"((("\\"")) ("0x5d10ffff"("c")) (("\\"")))) ()) "none"()) (("}"))) ()) "none"()) (("]"))) ())) "some"(((((",")) (" "(" "))) ("string"((("\\"")) ("0x5d10ffff"("a")) (("\\""))) ())) "none"())))) (("]")))) (" "(" "))) "none"()) (("}"))) (" "(" ") " "(" ")))')
+            expectAst('   { "q": [ 12, false, [{}], "a"] }  ', '((" "(" ") " "(" ") " "(" ")) "object"((("{")) (" "(" ")) "some"(((((("\\"")) ("0x5d10ffff"("q")) (("\\""))) () ((":")) (" "(" ")) "array"((("[")) (" "(" ")) "some"(("number"("none"() "onenine"(("1") (("2"))) "none"() "none"()) ()) "some"(((((",")) (" "(" "))) ("false"(("f") ("a") ("l") ("s") ("e")) ())) "some"(((((",")) (" "(" "))) ("array"((("[")) () "some"(("object"((("{")) () "none"() (("}"))) ()) "none"()) (("]"))) ())) "some"(((((",")) (" "(" "))) ("string"((("\\"")) ("0x5d10ffff"("a")) (("\\""))) ())) "none"())))) (("]")))) (" "(" "))) "none"()) (("}"))) (" "(" ") " "(" ")))')
+            expectAst('   [{ "q": [ 12, false, [{}], "a"] }]  ', '((" "(" ") " "(" ") " "(" ")) "array"((("[")) () "some"(("object"((("{")) (" "(" ")) "some"(((((("\\"")) ("0x5d10ffff"("q")) (("\\""))) () ((":")) (" "(" ")) "array"((("[")) (" "(" ")) "some"(("number"("none"() "onenine"(("1") (("2"))) "none"() "none"()) ()) "some"(((((",")) (" "(" "))) ("false"(("f") ("a") ("l") ("s") ("e")) ())) "some"(((((",")) (" "(" "))) ("array"((("[")) () "some"(("object"((("{")) () "none"() (("}"))) ()) "none"()) (("]"))) ())) "some"(((((",")) (" "(" "))) ("string"((("\\"")) ("0x5d10ffff"("a")) (("\\""))) ())) "none"())))) (("]")))) (" "(" "))) "none"()) (("}"))) ()) "none"()) (("]"))) (" "(" ") " "(" ")))')
+
+            expectNoMatch('   tr2ue   ')
+            expectNoMatch('   true"   ')
+            expectNoMatch('   "Hello   ')
+            expectNoMatch('   h-56.7e+5   ')
+            expectNoMatch('   -56.7e+5   3')
+            expectNoMatch('   [ 12, false2, "a"]  ')
+            expectNoMatch('   { "q": [ 12, false, [}], "a"] }  ')
+
+            // The invalid input in detail. A failed match's own index rewound to
+            // the start and locates nothing; the furthest failure is the
+            // high-water mark, and it lands on the `}` that closes nothing.
+            const bad = '   [{ "q": [ 12, false, [}], "a"] }]  '
+            const badMr = descentParserCpOnly(m, '', toArray(stringToCodePointList(bad)))
+            assertEq(badMr.success, false, bad)
+            assertEq(badMr.idx, 0, bad)
+            const failure = assertNotNullish(badMr.failure)
+            assertEq(failure.idx, 25, bad)
+            assertEq(bad[failure.idx], '}', bad)
         }
     ],
     // Regression for the stack-recursive matcher bug: the matcher used to recurse
@@ -323,6 +356,135 @@ export const proof = {
             if (result !== `{"ast":{"sequence":[{"tag":"minus","sequence":[[${cp1('-')},"minus"]]},{"sequence":[[${cp1('2')},"two"]]}]},"success":true,"idx":2}`) { throw result }
         },
     ],
+    logicalEof: [
+        () => {
+            // The matcher synthesizes one EOF after the physical input, so the
+            // `eof` terminal matches empty input. It contributes no AST leaf,
+            // and the public index stays physical.
+            const m = descentParser(eof)
+            const mr = m('', [])
+            assertEq(JSON.stringify(mr), '{"ast":{"sequence":[]},"success":true,"idx":0}')
+        },
+        () => {
+            // Callers pass physical symbols only, so EOF is not available
+            // before the end of the input.
+            const m = descentParser(eof)
+            const mr = descentParserCpOnly(m, '', toArray(stringToCodePointList('A')))
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], eof)
+        },
+        () => {
+            // Non-empty input: the terminal consumes the synthesized EOF after
+            // the last code point, and `idx` still reports `input.length`.
+            const m = descentParser([range('AA'), eof])
+            const cp = toArray(stringToCodePointList('A'))
+            const mr = descentParserCpOnly(m, '', cp)
+            assertEq(mr.success, true)
+            assertEq(mr.idx, cp.length)
+            assertEq(JSON.stringify(mr.ast), `{"sequence":[{"sequence":[[${cp1('A')},null]]},{"sequence":[]}]}`)
+        },
+        () => {
+            // Exactly one EOF is synthesized: a second `eof` terminal has
+            // nothing left to consume, and its failure points at `input.length`.
+            const m = descentParser([eof, eof])
+            const mr = m('', [])
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], eof)
+        },
+        () => {
+            // EOF as one alternative among ordinary terminals.
+            const m = descentParser({ a: range('AA'), e: eof })
+            assertEq(JSON.stringify(m('', [])), '{"ast":{"tag":"e","sequence":[]},"success":true,"idx":0}')
+            const mr = descentParserCpOnly(m, '', toArray(stringToCodePointList('A')))
+            assertEq(mr.success, true)
+            assertEq(mr.idx, 1)
+        },
+        () => {
+            // Repetition terminates on EOF: consuming it moves the complete
+            // cursor, so the repeat makes exactly one round and then stops —
+            // with `idx` alone this would never stop.
+            const rule = repeat0Plus(eof)
+            const m = descentParser(rule)
+            const mr = m(toData(rule)[1], [])
+            assertEq(JSON.stringify(mr), '{"ast":{"sequence":[{"sequence":[]}]},"success":true,"idx":0}')
+        },
+        () => {
+            // Backtracking restores the complete cursor: `x` consumes EOF and
+            // then fails, so `y` must still find EOF available.
+            const m = descentParser({ x: [eof, range('AA')], y: eof })
+            assertEq(JSON.stringify(m('', [])), '{"ast":{"tag":"y","sequence":[]},"success":true,"idx":0}')
+        },
+        () => {
+            // Diagnostic ordering by the complete cursor: `y` got further than
+            // `x` — the same physical index, but past the EOF it consumed — so
+            // only its expectation is reported, and at the physical end.
+            const m = descentParser({ x: range('AA'), y: [eof, range('BB')] })
+            const mr = m('', [])
+            assertEq(mr.success, false)
+            const f = assertNotNullish(mr.failure)
+            assertEq(f.idx, 0)
+            assertEq(f.expected.length, 1)
+            assertEq(f.expected[0], range('BB'))
+        },
+    ],
+    repeat: [
+        () => {
+            // The whole repetition is one node holding a flat sequence of the
+            // items it matched — not the right-recursive chain of `some`/`none`
+            // nodes its functional spelling builds.
+            const rule = repeat0Plus(set(' \n\r\t'))
+            const m = descentParser(rule)
+            const name = toData(rule)[1]
+            const mr = descentParserCpOnly(m, name, toArray(stringToCodePointList('  ')))
+            assertEq(
+                JSON.stringify(mr),
+                `{"ast":{"sequence":[{"tag":" ","sequence":[[${cp1(' ')},null]]},{"tag":" ","sequence":[[${cp1(' ')},null]]}]},"success":true,"idx":2}`)
+        },
+        () => {
+            // Zero items is a match, and the node is empty rather than tagged.
+            const rule = repeat0Plus(set(' \n\r\t'))
+            const m = descentParser(rule)
+            const mr = m(toData(rule)[1], [])
+            assertEq(JSON.stringify(mr), '{"ast":{"sequence":[]},"success":true,"idx":0}')
+        },
+        () => {
+            // A round that fails ends the repetition rather than failing it: the
+            // rounds before it stand and the match stops where the failed one
+            // began.
+            const rule = repeat0Plus(set(' \n\r\t'))
+            const m = descentParser(rule)
+            const name = toData(rule)[1]
+            const mr = descentParserCpOnly(m, name, toArray(stringToCodePointList(' x')))
+            assertEq(
+                JSON.stringify(mr),
+                `{"ast":{"sequence":[{"tag":" ","sequence":[[${cp1(' ')},null]]}]},"success":true,"idx":1}`)
+        },
+        () => {
+            // `toData` never folds a nullable item into a `repeat`, but a
+            // hand-written rule set can hold one. A round that consumes nothing
+            // would repeat forever, so it is kept once and ends the repetition.
+            /** @type {RuleSet} */
+            const ruleSet = {
+                repeated: 'optionalA',
+                optionalA: { some: 'a', none: 'e' },
+                a: range('aa'),
+                e: [],
+            }
+            const m = descentParserRuleSet(ruleSet)
+            assertEq(
+                JSON.stringify(m('repeated', [])),
+                '{"ast":{"sequence":[{"tag":"none","sequence":[]}]},"success":true,"idx":0}')
+            assertEq(
+                JSON.stringify(m('repeated', [[cp1('a'), null]])),
+                `{"ast":{"sequence":[{"tag":"some","sequence":[[${cp1('a')},null]]},{"tag":"none","sequence":[]}]},"success":true,"idx":1}`)
+        },
+    ],
     furthestFailure: [
         () => {
             // A branch rejected *before* the high-water mark must not pull it back:

package/fjs/bnf/descent/types.d.ts

@@ -1,15 +1,22 @@
 /**
  * Types for the recursive descent matcher backend.
  *
+ * The AST it builds is the shared one, over leaves that carry metadata:
+ * `Ast<CodePointMeta<T>>` from [`../matcher`](../matcher). What is declared
+ * here is what belongs to *this* backend — the metadata-carrying leaf, the
+ * diagnostics a backtracking matcher can report, and its public result.
+ *
  * @module
  */
 import type { CodePoint } from '../../text/utf16/types.ts';
+import type { Ast, AstTag } from '../matcher/types.ts';
 import type { TerminalRange } from '../types.ts';
-export type AstTag = string | true | undefined;
 /**
- * Recursive descent matcher for a single named rule.
+ * Recursive descent matcher for a single named rule, starting from `startPos` —
+ * a position that counts the synthesized end-of-input symbol, unlike the public
+ * `idx` of the result.
  */
-export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePointMeta<T>[], idx: number) => DescentMatchResult<T>;
+export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePointMeta<T>[], startPos: number) => DescentMatchResult<T>;
 /**
  * Where a match ran out of road, for diagnostics.
  *
@@ -24,6 +31,11 @@ export type DescentMatchRule<T> = (name: string, tag: AstTag, s: readonly CodePo
  *
  * `idx` is `0` with an empty `expected` when the match failed without ever
  * rejecting a terminal, as an empty variant does.
+ *
+ * `idx` is physical, so a terminal rejected at — or past — the synthesized
+ * end-of-input symbol reports `input.length`. The high-water mark itself is
+ * kept on the complete cursor, so those two are still ordered against each
+ * other and their expected terminals do not merge.
  */
 export type DescentFailure = {
     readonly idx: number;
@@ -41,11 +53,12 @@ export type DescentFailure = {
  * On failure `idx` has rewound to the start of the enclosing sequence and
  * locates nothing; read `failure.idx` instead.
  *
- * The same type describes a match in progress, where `failure` is likewise
- * absent until the match ends.
+ * `idx` is physical — `0 <= idx <= input.length` — so a match that consumed the
+ * synthesized end-of-input symbol reports `input.length`, the same as one that
+ * stopped just before it.
  */
 export type DescentMatchResult<T> = {
-    readonly ast: AstRuleMeta<T>;
+    readonly ast: Ast<CodePointMeta<T>>;
     readonly success: boolean;
     readonly idx: number;
     readonly failure?: DescentFailure;
@@ -55,17 +68,10 @@ export type DescentMatchResult<T> = {
  */
 export type DescentMatch<T> = (name: string, s: readonly CodePointMeta<T>[]) => DescentMatchResult<T>;
 /**
- * Code point value paired with metadata.
+ * Code point value paired with metadata: this backend's AST leaf.
+ *
+ * Preserving metadata per consumed code point is what distinguishes this
+ * backend, so the leaf type stays here rather than moving to the shared layer,
+ * which is parameterized by it.
  */
 export type CodePointMeta<T> = readonly [CodePoint, T];
-/**
- * AST sequence for the metadata-aware parser.
- */
-export type AstSequenceMeta<T> = readonly (AstRuleMeta<T> | CodePointMeta<T>)[];
-/**
- * Metadata-aware AST node.
- */
-export type AstRuleMeta<T> = {
-    readonly tag: AstTag;
-    readonly sequence: AstSequenceMeta<T>;
-};

package/fjs/bnf/ll1/module.f.d.mts

@@ -4,26 +4,59 @@
  * Built from the serializable IR in `fjs/bnf/data`, this is one member of the
  * family of automaton builders that consume a {@link RuleSet}: it compiles the
  * grammar into a predictive {@link dispatchMap} and matches input into an AST
- * ({@link MatchResult}). It throws at build time (`can not merge …`) when the
- * grammar is not LL(1) — a first/first conflict. Nullability is looked up from
- * {@link emptyTagMap} in `fjs/bnf/data` rather than re-derived here.
+ * ({@link MatchResult}). It throws at build time when the grammar is not
+ * LL(1): `can not merge …` for a first/first conflict, `left recursion …` for
+ * a rule reachable from itself in first position. Nullability is looked up
+ * from {@link emptyTagMap} in `fjs/bnf/data` rather than re-derived here.
+ *
+ * A rule is entered *before* its first symbol is consumed: the dispatch map
+ * only selects — a variant's branch, a repetition's next round — and every
+ * rule invocation builds a node of its own, so the AST is the one
+ * `fjs/bnf/descent` builds for the same grammar (see ./README.md). A `Repeat`
+ * rule is matched iteratively and produces one node holding a flat sequence
+ * of the items it matched.
+ *
+ * The caller passes physical symbols only; the matcher synthesizes the one
+ * logical EOF after them, so a grammar can dispatch on the end of input with
+ * the `eof` terminal. The position it does that at, the AST it builds, and the
+ * constructors that pair them are the shared layer in `fjs/bnf/matcher`.
  *
  * See `./types.ts` for the type-level API.
  *
  * @module
  *
+ * @import { CodePoint } from '../../text/utf16/types.ts'
  * @import { Properties } from '../../types/range_map/types.ts'
  * @import { StringSet } from '../../types/string_set/types.ts'
- * @import { EmptyTag, RuleSet } from '../data/types.ts'
+ * @import { List } from '../../types/list/types.ts'
+ * @import { RuleSet, Sequence } from '../data/types.ts'
+ * @import { Ast, AstResult, AstSequence, AstTag, Cursor } from '../matcher/types.ts'
  * @import { Rule as FRule } from '../types.ts'
- * @import { AstSequence, AstTag, Match, MatchResult, MatchRule, Remainder, _Dispatch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
+ * @import { Match, MatchResult, Remainder, _Dispatch, _DispatchBranch, _DispatchMap, _DispatchResult, _DispatchRule } from './types.ts'
  */
-import type { RuleSet } from '../data/types.ts';
+import type { CodePoint } from '../../text/utf16/types.ts';
+import type { List } from '../../types/list/types.ts';
+import type { RuleSet, Sequence } from '../data/types.ts';
+import type { Ast, AstResult, AstSequence, AstTag, Cursor } from '../matcher/types.ts';
 import type { Rule as FRule } from '../types.ts';
 import type { Match, _DispatchMap } from './types.ts';
 /**
  * Builds a dispatch map for a {@link RuleSet} to enable predictive parsing.
  *
+ * Each rule's entry holds the rule's first set as a range map. Only a variant
+ * reads the value under a symbol — the branch that lookahead selects; every
+ * other reader asks whether a symbol is in the set at all, which is how a
+ * repetition decides to start another round. `empty` is the branch a variant
+ * takes when no entry matches the lookahead — its nullable branch, absent
+ * when the variant cannot match empty.
+ *
+ * A rule referenced in first position while its own first set is still being
+ * computed is left recursion — a grammar no lookahead can decide, whose match
+ * would loop at the same position forever — so building throws
+ * (`left recursion …`) rather than letting the matcher diverge. The one
+ * self-reference with a sound reading is a repetition of itself: zero rounds
+ * match whatever the item does, so it dispatches on nothing and matches empty.
+ *
  * @type {(ruleSet: RuleSet) => _DispatchMap}
  */
 export declare const dispatchMap: (ruleSet: RuleSet) => _DispatchMap;
@@ -33,6 +66,41 @@ export declare const dispatchMap: (ruleSet: RuleSet) => _DispatchMap;
  * @type {(fr: FRule) => Match}
  */
 export declare const parser: (fr: FRule) => Match;
+export type _Position = Cursor | null;
+export type _Result = AstResult<CodePoint, _Position>;
+export type _SeqFrame = {
+    readonly kind: 'seq';
+    readonly tag: AstTag;
+    readonly items: Sequence;
+    readonly itemIndex: number;
+    readonly seq: AstSequence<CodePoint>;
+};
+export type _RepeatFrame = {
+    readonly kind: 'repeat';
+    readonly tag: AstTag;
+    readonly item: string;
+    readonly items: _Items;
+};
+export type _Items = List<Ast<CodePoint>>;
+export type _Frame = _SeqFrame | _RepeatFrame;
+export type _Stack = null | {
+    readonly top: _Frame;
+    readonly rest: _Stack;
+};
+export type _RuleTask = {
+    readonly kind: 'rule';
+    readonly name: string;
+    readonly tag: AstTag;
+    readonly pos: Cursor;
+};
+export type _RepeatTask = {
+    readonly kind: 'repeat';
+    readonly tag: AstTag;
+    readonly item: string;
+    readonly items: _Items;
+    readonly pos: Cursor;
+};
+export type _Task = _RuleTask | _RepeatTask;
 /**
  * Creates an LL(1) parser from an already materialized {@link RuleSet}.
  *