functionalscript 0.43.1 → 0.45.0

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

@@ -0,0 +1,413 @@
+/**
+ * @module
+ *
+ * @import { RuleSet } from '../data/types.ts'
+ * @import { MatchResult } from './types.ts'
+ */
+
+import { stringToCodePointList } from '../../text/utf16/module.f.mjs'
+import { toArray } from '../../types/list/module.f.mjs'
+import { commaJoin0Plus, eof, option, range, repeat0Plus, set } from '../module.f.mjs'
+import { toData } from '../data/module.f.mjs'
+import { dispatchMap, parser, parserRuleSet } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+import { deterministic } from '../testlib.f.mjs'
+
+export const proof = {
+    dispatch: [
+        () => {
+            const terminalRangeRule = range('AF')
+            const data = toData(terminalRangeRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"":{"rangeMap":[[null,64],[{"rules":[]},70]]}}') { throw result }
+        },
+        () => {
+            const stringRule = 'AB'
+            const data = toData(stringRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"rangeMap":[[null,64],[{"rules":[]},65]]},"1":{"rangeMap":[[null,65],[{"rules":[]},66]]},"":{"rangeMap":[[null,64],[{"rules":["1"]},65]]}}') { throw result }
+        },
+        () => {
+            const a = range('AA')
+            const b = range('BB')
+            const ab = [a, b]
+            const data = toData(ab)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"rangeMap":[[null,64],[{"rules":[]},65]]},"1":{"rangeMap":[[null,65],[{"rules":[]},66]]},"":{"rangeMap":[[null,64],[{"rules":["1"]},65]]}}') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const data = toData(emptyRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"":{"emptyTag":true,"rangeMap":[]}}') { throw result }
+        },
+        () => {
+            const variantRule = { 'a': range('AA'), 'b': range('BB')}
+            const data = toData(variantRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"rangeMap":[[null,64],[{"rules":[]},65]]},"1":{"rangeMap":[[null,65],[{"rules":[]},66]]},"":{"rangeMap":[[null,64],[{"tag":"a","rules":[]},65],[{"tag":"b","rules":[]},66]]}}') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const variantRule = { 'e': emptyRule, 'a': range('AA')}
+            const data = toData(variantRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"emptyTag":true,"rangeMap":[]},"1":{"rangeMap":[[null,64],[{"rules":[]},65]]},"":{"emptyTag":"e","rangeMap":[[null,64],[{"tag":"a","rules":[]},65]]}}') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const minursRule = range('--')
+            const optionalMinusRule = { 'none': emptyRule, 'minus': minursRule}
+            const digitRule = range('09')
+            const numberRule = [optionalMinusRule, digitRule]
+            const data = toData(numberRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"emptyTag":"none","rangeMap":[[null,44],[{"tag":"minus","rules":[]},45]]},"1":{"emptyTag":true,"rangeMap":[]},"2":{"rangeMap":[[null,44],[{"rules":[]},45]]},"3":{"rangeMap":[[null,47],[{"rules":[]},57]]},"":{"rangeMap":[[null,44],[{"tag":"minus","rules":["3"]},45],[null,47],[{"rules":[]},57]]}}') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const spaceRule = range('  ')
+            const optionalSpaceRule = { 'none': emptyRule, 'space': spaceRule}
+            const minusRule = range('--')
+            const optionalMinusRule = { 'none': emptyRule, 'minus': minusRule}
+            const digitRule = range('09')
+            const numberRule = [optionalSpaceRule, optionalMinusRule, digitRule]
+            const data = toData(numberRule)
+            const dm = dispatchMap(data[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"0":{"emptyTag":"none","rangeMap":[[null,31],[{"tag":"space","rules":[]},32]]},"1":{"emptyTag":true,"rangeMap":[]},"2":{"rangeMap":[[null,31],[{"rules":[]},32]]},"3":{"emptyTag":"none","rangeMap":[[null,44],[{"tag":"minus","rules":[]},45]]},"4":{"rangeMap":[[null,44],[{"rules":[]},45]]},"5":{"rangeMap":[[null,47],[{"rules":[]},57]]},"":{"rangeMap":[[null,31],[{"tag":"space","rules":["3","5"]},32],[null,44],[{"tag":"minus","rules":["5"]},45],[null,47],[{"rules":[]},57]]}}') { throw result }
+        }
+    ],
+    parser: [
+        () => {
+            const emptyRule = ''
+            const m = parser(emptyRule)
+            const mr = m("", [])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":true,"sequence":[]},true,[]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const m = parser(emptyRule)
+            const mr = m("", [65, 70])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":true,"sequence":[]},true,[65,70]]') { throw result }
+        },
+        () => {
+            const terminalRangeRule = range('AF')
+            const m = parser(terminalRangeRule)
+            const mr = m("", [65])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[65]},true,[]]') { throw result }
+        },
+        () => {
+            const terminalRangeRule = 0x000079_000087
+            const m = parser(terminalRangeRule)
+            const mr = m("", [64])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},false,[64]]') { throw result }
+        },
+        () => {
+            const terminalRangeRule = 0x000080_000087 //broken range
+            const m = parser(terminalRangeRule)
+            const mr = m("", [64])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},false,[64]]') { throw result }
+        },
+        () => {
+            const variantRule = { 'a': range('AA'), 'b': range('BB')}
+            const m = parser(variantRule)
+            const mr = m("", [65])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":"a","sequence":[65]},true,[]]') { throw result }
+        },
+        () => {
+            const variantRule = { 'a': range('AA'), 'b': range('BB')}
+            const m = parser(variantRule)
+            const mr = m("", [64])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},false,[64]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const variantRule = { 'e': emptyRule, 'a': range('AA')}
+             const m = parser(variantRule)
+            const mr = m("", [])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":"e","sequence":[]},true,[]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const variantRule = { 'e': emptyRule, 'a': range('AA')}
+            const m = parser(variantRule)
+            const mr = m("", [64])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":"e","sequence":[]},true,[64]]') { throw result }
+        },
+        () => {
+            const stringRule = 'AB'
+            const m = parser(stringRule)
+            const mr = m("", [65,66])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[65,{"sequence":[66]}]},true,[]]') { throw result }
+        },
+        () => {
+            const stringRule = 'AB'
+            const m = parser(stringRule)
+            const mr = m("", [65,67])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},false,[67]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const minursRule = range('--')
+            const optionalMinusRule = { 'none': emptyRule, 'minus': minursRule}
+            const digitRule = range('09')
+            const numberRule = [optionalMinusRule, digitRule]
+            const m = parser(numberRule)
+            const mr = m("", [50])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[50]},true,[]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const minusRule = range('--')
+            const optionalMinusRule = { 'none': emptyRule, 'minus': minusRule}
+            const digitRule = range('09')
+            const numberRule = [optionalMinusRule, digitRule]
+            const m = parser(numberRule)
+            const mr = m("", [45,50])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"tag":"minus","sequence":[45,{"sequence":[50]}]},true,[]]') { throw result }
+        },
+        () => {
+            const emptyRule = ''
+            const minusRule = range('--')
+            const optionalMinusRule = { 'none': emptyRule, 'minus': minusRule}
+            const digitRule = range('09')
+            const numberRule = [optionalMinusRule, digitRule]
+            const m = parser(numberRule)
+            const mr = m("", [])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},true,null]') { throw result } //if remainder is null it means failed
+        },
+        () => {
+            const m = parser(option('a'))
+
+            const isSuccess = (/** @type {MatchResult} */mr) => mr[1] && mr[2]?.length === 0
+            /** @type {(s: string, success: boolean) => void} */
+            const expect = (s, success) => {
+                const mr = m('', toArray(stringToCodePointList(s)))
+                assertEq(isSuccess(mr), success, mr)
+            }
+
+            expect('a', true)
+            expect('', true)
+            expect('aa', false)
+            expect('b', false)
+        },
+        () => {
+            const ws = repeat0Plus(set(' \n\r\t'))
+
+            const cj = commaJoin0Plus(ws)
+
+            const value = () => ({
+                object: cj('{}', 'a'),
+                array: cj('[]', 'a')
+            })
+
+            value.name //bun will fail if no usage of name found
+
+            const m = parser(value)
+
+            /** @type {(mr: MatchResult) => boolean} */
+            const isSuccess = mr => mr[1] && mr[2]?.length === 0
+            /** @type {(s: string, success: boolean) => void} */
+            const expect = (s, success) => {
+                const mr = m('value', toArray(stringToCodePointList(s)))
+                assertEq(isSuccess(mr), success, mr)
+            }
+
+            expect('', false)
+            expect('[]', true)
+            expect('[a]', true)
+            expect('[a, a]', true)
+            expect('{a}', true)
+        },
+        () => {
+            const m = parser(deterministic())
+
+            /** @type {(mr: MatchResult) => boolean} */
+            const isSuccess = (mr) => mr[1] && mr[2]?.length === 0
+            /** @type {(s: string, success: boolean) => void} */
+            const expect = (s, success) => {
+                const mr = m('', toArray(stringToCodePointList(s)))
+                assertEq(isSuccess(mr), success, mr)
+            }
+
+            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)
+        }
+    ],
+    longInput: [
+        () => {
+            // Long right-recursive repetition: one `repeat0Plus` chain across the
+            // whole input. This is the shape that overflowed the JS call stack
+            // when the matcher recursed once per consumed code point.
+            const m = parser(repeat0Plus(set(' \n\r\t')))
+            const [, success, remainder] = m('', toArray(stringToCodePointList(' '.repeat(10000))))
+            assertEq(success, true)
+            assertEq(remainder?.length, 0)
+        },
+        () => {
+            // Deep non-repetition nesting: 5000 bracket levels in the JSON-like
+            // test grammar — a shape a repetition-specific fix would not cover.
+            const m = parser(deterministic())
+            const n = 5000
+            const cp = toArray(stringToCodePointList('['.repeat(n) + ']'.repeat(n)))
+            const [, success, remainder] = m('', cp)
+            assertEq(success, true)
+            assertEq(remainder?.length, 0)
+        },
+    ],
+    logicalEof: [
+        () => {
+            // EOF dispatches below every ordinary symbol, so its cut point is
+            // `-2` — the stored endpoint codes never reach the dispatch map.
+            const dm = dispatchMap(toData(eof)[0])
+            assertEq(JSON.stringify(dm), '{"":{"rangeMap":[[null,-2],[{"rules":[]},-1]]}}')
+        },
+        () => {
+            // The matcher synthesizes one EOF after the physical input, so an
+            // `eof` terminal matches empty input. It adds no AST leaf, and the
+            // remainder stays physical: empty, not `null`.
+            const m = parser(eof)
+            assertEq(JSON.stringify(m('', [])), '[{"sequence":[]},true,[]]')
+        },
+        () => {
+            // Callers pass physical symbols only, so EOF is not available
+            // before the end of the input.
+            const m = parser(eof)
+            assertEq(JSON.stringify(m('', [65])), '[{"sequence":[]},false,[65]]')
+        },
+        () => {
+            // Non-empty input: the terminal consumes the synthesized EOF after
+            // the last code point.
+            const m = parser([range('AA'), eof])
+            assertEq(JSON.stringify(m('', [65])), '[{"sequence":[65,{"sequence":[]}]},true,[]]')
+        },
+        () => {
+            // Exactly one EOF is synthesized: the second `eof` terminal has
+            // nothing to consume, so the match runs out of input — the `null`
+            // remainder this backend reports for that.
+            const m = parser([eof, eof])
+            assertEq(JSON.stringify(m('', [])), '[{"sequence":[{"sequence":[]}]},true,null]')
+        },
+        () => {
+            // EOF as one alternative among ordinary terminals.
+            const m = parser({ a: range('AA'), e: eof })
+            assertEq(JSON.stringify(m('', [])), '[{"tag":"e","sequence":[]},true,[]]')
+            assertEq(JSON.stringify(m('', [65])), '[{"tag":"a","sequence":[65]},true,[]]')
+        },
+    ],
+    repeat: [
+        () => {
+            /** @type {readonly [RuleSet, string]} */
+            const repeatData = [{"":["ws","repa"],"ws":[],"repa":["a",""],"a":1090519105},""]
+            const dm = dispatchMap(repeatData[0])
+            const result = JSON.stringify(dm)
+            if (result !== '{"ws":{"emptyTag":true,"rangeMap":[]},"a":{"rangeMap":[[null,64],[{"rules":[]},65]]},"repa":{"rangeMap":[[null,64],[{"rules":[""]},65]]},"":{"rangeMap":[[null,64],[{"rules":[""]},65]]}}') { throw result }
+        }
+    ],
+    repeatParser: [
+        () => {
+            /** @type {readonly [RuleSet, string]} */
+            const repeatData = [{"":["ws","repa"],"ws":[],"repa":["a",""],"a":1090519105},""]
+            const m = parserRuleSet(repeatData[0])
+            const mr = m("", [])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},true,null]') { throw result }
+        },
+        () => {
+            /** @type {readonly [RuleSet, string]} */
+            const repeatData = [{"":["ws","repa"],"ws":[],"repa":["a",""],"a":1090519105},""]
+            const m = parserRuleSet(repeatData[0])
+            const mr = m("", [65])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[65,{"sequence":[]}]},true,null]') { throw result }
+        },
+        () => {
+            /** @type {readonly [RuleSet, string]} */
+            const repeatData = [{"":["ws","repa"],"ws":[],"repa":["a",""],"a":1090519105},""]
+            const m = parserRuleSet(repeatData[0])
+            const mr = m("", [65,65,65])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[65,{"sequence":[65,{"sequence":[65,{"sequence":[]}]}]}]},true,null]') { throw result }
+        },
+        () => {
+            /** @type {readonly [RuleSet, string]} */
+            const repeatData = [{"":["ws","repa"],"ws":[],"repa":["a",""],"a":1090519105},""]
+            const m = parserRuleSet(repeatData[0])
+            const mr = m("", [66])
+            const result = JSON.stringify(mr)
+            if (result !== '[{"sequence":[]},false,[66]]') { throw result }
+        }
+    ],
+    throw: {
+        ambiguousVariantDispatch: () => {
+            // Two alternatives covering the same code point — dispatch merge throws.
+            const conflictRule = { 'a': range('AA'), 'b': range('AA') }
+            dispatchMap(toData(conflictRule)[0])
+        }
+    },
+    // Regression: `emptyTagMap` must stay correct for cyclic rule references.
+    // A naive single-pass, memoized derivation that marks a rule nullable as
+    // a placeholder *before* recursing into its own children (to break the
+    // cycle) over-approximates nullability here, and made `dispatchMap`
+    // falsely report a first/first conflict for this grammar even though it
+    // has none — `value` only ever nests inside brackets or is the literal
+    // `a`, and `ws` is genuinely optional on both sides of it.
+    cyclicNullability: () => {
+        const ws = option(' ')
+        const value = () => ({ array: ['[', value, ']'], leaf: 'a' })
+        const m = parser([ws, value, ws]) // must not throw 'can not merge'
+
+        /** @type {(s: string, success: boolean) => void} */
+        const expect = (s, success) => {
+            const mr = m('', toArray(stringToCodePointList(s)))
+            assertEq(mr[1] && mr[2]?.length === 0, success, mr)
+        }
+
+        expect('a', true)
+        expect(' a ', true)
+        expect('[a]', true)
+        expect('[[a]]', true)
+        expect(' [[a]] ', true)
+        expect('b', false)
+    },
+}

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

@@ -0,0 +1,65 @@
+/**
+ * Types for the LL(1) dispatch/matcher backend.
+ *
+ * @module
+ */
+import type { CodePoint } from '../../text/utf16/types.ts';
+import type { RangeMapArray } from '../../types/range_map/types.ts';
+import type { StringMap } from '../../types/object/types.ts';
+import type { EmptyTag } from '../data/types.ts';
+/** @internal */
+export type _DispatchRule = {
+    readonly emptyTag: EmptyTag;
+    readonly rangeMap: _Dispatch;
+};
+/** @internal */
+export type _Dispatch = RangeMapArray<_DispatchResult>;
+/** @internal */
+export type _DispatchResult = _DispatchRuleCollection | null;
+/**
+ * The rules a dispatched symbol selects, to be matched one after another. They
+ * are names into the {@link _DispatchMap}: the builder only ever appends rule
+ * names, so the matcher resolves each one there.
+ *
+ * @internal
+ */
+export type _DispatchRuleCollection = {
+    readonly tag: string | undefined;
+    readonly rules: readonly string[];
+};
+/** @internal */
+export type _DispatchMap = StringMap<_DispatchRule>;
+/**
+ * Represents a parsed AST rule, consisting of a rule name and its parsed sequence.
+ *
+ * @internal
+ */
+export type _AstRule = {
+    readonly tag: AstTag;
+    readonly sequence: AstSequence;
+};
+/**
+ * Represents a parsed AST sequence.
+ */
+export type AstSequence = readonly (_AstRule | CodePoint)[];
+export type AstTag = string | true | undefined;
+/**
+ * Represents the remaining input after a match attempt, or `null` if no match is possible.
+ *
+ * The remainder is physical: consuming the synthesized end-of-input symbol
+ * leaves it empty rather than making it `null`.
+ */
+export type Remainder = readonly CodePoint[] | null;
+/**
+ * Parsing result of `parser` and `parserRuleSet`.
+ *
+ * Represents the result of a match operation, including the parsed AST rule and the remainder of the input.
+ */
+export type MatchResult = readonly [_AstRule, boolean, Remainder];
+/**
+ * LL(1) parser function for matching by rule name.
+ *
+ * `s` holds physical symbols only; the matcher synthesizes the one logical
+ * end-of-input symbol after them.
+ */
+export type Match = (name: string, s: readonly CodePoint[]) => MatchResult;

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

@@ -0,0 +1,173 @@
+/**
+ * Core BNF grammar primitives and helpers for describing parser rules.
+ *
+ * The module provides terminal-range encoding utilities, rule composition
+ * types, and set/range helpers used by FunctionalScript grammar definitions.
+ * See `./types.ts` for the type-level API.
+ *
+ * @module
+ *
+ * @import { Tuple } from '../types/array/types.ts'
+ * @import { TerminalRange, Sequence, Rule, RangeVariant, None, Option, Repeat0Plus, Repeat1Plus, Join1Plus, Repeat } from './types.ts'
+ */
+import type { Tuple } from '../types/array/types.ts';
+import type { TerminalRange, Sequence, Rule, RangeVariant, None, Option, Repeat0Plus, Repeat1Plus, Join1Plus, Repeat } from './types.ts';
+/**
+ * The logical end-of-input symbol.
+ *
+ * `-1` is outside the non-negative physical-symbol domain, so no alphabet
+ * adapter can produce it and no ordinary symbol has to be reserved for it.
+ * Parser backends synthesize it exactly once, after the physical input.
+ */
+export declare const eofSymbol = -1;
+/** @type {(a: number, b: number) => TerminalRange} */
+export declare const rangeEncode: (a: number, b: number) => TerminalRange;
+/**
+ * Encodes a single symbol as a {@link TerminalRange}.
+ *
+ * @type {(a: number) => TerminalRange}
+ */
+export declare const oneEncode: (a: number) => TerminalRange;
+/**
+ * End-of-file marker: the singleton range of {@link eofSymbol}. Deliberately
+ * outside the ordinary symbol domain — and so outside Unicode — so it can
+ * never collide with a real code point.
+ *
+ * @type {TerminalRange}
+ */
+export declare const eof: TerminalRange;
+/**
+ * Every ordinary symbol packed into a single {@link TerminalRange}. EOF is not
+ * one of them, so complements over this range never include it.
+ *
+ * @type {TerminalRange}
+ */
+export declare const fullRange: TerminalRange;
+/**
+ * Unicode scalar value range packed into a single {@link TerminalRange}.
+ * @type {TerminalRange}
+ */
+export declare const unicodeRange: TerminalRange;
+/**
+ * Maximal Unicode code point encoded as a string value.
+ */
+export declare const unicodeMax: string;
+/**
+ * Decodes a packed range into `[start, end]` semantic symbols.
+ *
+ * @type {(r: number) => Tuple<2, number>}
+ */
+export declare const rangeDecode: (r: number) => Tuple<2, number>;
+/** @type {(s: string) => readonly TerminalRange[]} */
+export declare const toSequence: (s: string) => readonly TerminalRange[];
+/**
+ * Converts the whole string into one rule:
+ * - a single {@link TerminalRange} when the string has one symbol,
+ * - a sequence of {@link TerminalRange} values when the string has multiple symbols.
+ *
+ * @type {(s: string) => readonly TerminalRange[] | TerminalRange}
+ */
+export declare const str: (s: string) => readonly TerminalRange[] | TerminalRange;
+/**
+ * Converts a string into a variant that maps each character to its symbol range.
+ *
+ * @type {(s: string) => RangeVariant}
+ */
+export declare const set: (s: string) => RangeVariant;
+/**
+ * Encodes a two-symbol string into a terminal range.
+ *
+ * @throws If `ab` does not contain exactly two unicode code points.
+ *
+ * @type {(ab: string) => TerminalRange}
+ */
+export declare const range: (ab: string) => TerminalRange;
+export type _RangeList = readonly TerminalRange[];
+/** @type {(range: TerminalRange, v: RangeVariant) => RangeVariant} */
+export declare const remove: (range: TerminalRange, v: RangeVariant) => RangeVariant;
+/**
+ * Returns the complement set of the provided ranges over {@link fullRange}.
+ *
+ * @type {(v: RangeVariant) => RangeVariant}
+ */
+export declare const not: (v: RangeVariant) => RangeVariant;
+/**
+ * Returns the complement set of a character set over {@link fullRange}.
+ *
+ * @type {(s: string) => RangeVariant}
+ */
+export declare const notSet: (s: string) => RangeVariant;
+/**
+ * Shared empty sequence literal.
+ *
+ * @type {None}
+ */
+export declare const none: None;
+/**
+ * Creates an option value from a required branch.
+ */
+export declare const option: <S extends Rule>(
+/**
+ * @template {Rule} S
+ * @param {S} some
+ * @returns {Option<S>}
+ */
+some: S) => Option<S>;
+/**
+ * Repeat zero or more times.
+ *
+ * https://english.stackexchange.com/questions/506480/single-word-quantifiers-for-zero-or-more-like-cardinalities
+ * - zero or more - any, 0Plus
+ * - one or more - several, 1Plus
+ *
+ * Also see: https://arbs.nzcer.org.nz/types-numbers
+ */
+export declare const repeat0Plus: <T extends Rule>(
+/**
+ * @template {Rule} T
+ * @param {T} some
+ * @returns {Repeat0Plus<T>}
+ */
+some: T) => Repeat0Plus<T>;
+/**
+ * Repeat one or more times.
+ */
+export declare const repeat1Plus: <T extends Rule>(
+/**
+ * @template {Rule} T
+ * @param {T} some
+ * @returns {Repeat1Plus<T>}
+ */
+some: T) => Repeat1Plus<T>;
+/**
+ * Repeats `some` one or more times separated by `separator`.
+ */
+export declare const join1Plus: <T extends Rule, S extends Rule>(some: T, separator: S) => Join1Plus<T, S>;
+/**
+ * Repeats `some` zero or more times separated by `separator`.
+ */
+export declare const join0Plus: <T extends Rule, S extends Rule>(some: T, separator: S) => Rule;
+/**
+ * A delimited, comma-separated list with whitespace between tokens:
+ * `open ws (item ws (',' ws item ws)*)? close`.
+ *
+ * `ws` is the per-grammar whitespace rule and is curried so callers can
+ * partially apply it once (`const cj = commaJoin0Plus(ws)`) before reusing
+ * the same combinator at multiple bracket pairs. The two-character string
+ * supplies the bracket pair via destructuring (e.g. `'[]'`, `'{}'`).
+ *
+ * @type {(ws: Rule) => (bracketPair: string, item: Rule) => Sequence}
+ */
+export declare const commaJoin0Plus: (ws: Rule) => (bracketPair: string, item: Rule) => Sequence;
+/**
+ * Repeats a rule a fixed number of times.
+ *
+ * @type {(n: number) => <T extends Rule>(some: T) => Repeat<T>}
+ */
+export declare const repeat: (n: number) => <T extends Rule>(some: T) => Repeat<T>;
+/**
+ * Determines whether the rule is an empty rule.
+ *
+ * @type {(rule: Rule) => boolean}
+ */
+export declare const isEmpty: (rule: Rule) => boolean;