trilean-regex 0.0.0 → 1.0.0

package/dist/matcher.js

@@ -0,0 +1,86 @@
+import { parseRegex } from "./parser.js";
+import { compileToNfa } from "./nfa.js";
+//#region src/matcher.ts
+/**
+* Epsilon-closure of `seeds` at absolute input position `pos` (0-based, counting the boundary *before* the character at that index -- so `pos === length` means "after the last character"): follows every `split` unconditionally and every `anchorStart`/`anchorEnd` only when `pos` satisfies it, stopping at each `char` or `match` state reached, which are the only kinds `matchesNfa`'s step loop ever needs to see.
+*
+* `length` is threaded through only for the `anchorEnd` check (`pos === length`) rather than read off a captured string, so this function depends on nothing beyond the automaton and two numbers -- it has no notion of "the input," only of where the boundary it is being asked about sits relative to the input's own length.
+*/
+function closure(nfa, seeds, pos, length) {
+	const result = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [...seeds];
+	while (stack.length > 0) {
+		const idx = stack.pop();
+		if (idx === void 0) continue;
+		if (visited.has(idx)) continue;
+		visited.add(idx);
+		const state = nfa.states[idx];
+		if (state === void 0) continue;
+		switch (state.kind) {
+			case "char":
+			case "match":
+				result.add(idx);
+				break;
+			case "split":
+				stack.push(state.to1, state.to2);
+				break;
+			case "anchorStart":
+				if (pos === 0) stack.push(state.to);
+				break;
+			case "anchorEnd": if (pos === length) stack.push(state.to);
+		}
+	}
+	return result;
+}
+/** The `char` states in `current` whose test accepts `codeUnit`, mapped to their (not yet closed) successor. Never includes `match` states -- there is nothing past a match to step from. */
+function step(nfa, current, codeUnit) {
+	const next = /* @__PURE__ */ new Set();
+	for (const idx of current) {
+		const state = nfa.states[idx];
+		if (state?.kind !== "char") continue;
+		if (state.test(codeUnit)) next.add(state.to);
+	}
+	return next;
+}
+/**
+* Simulates `nfa` against `input` and reports whether any substring of `input` matches -- the same "search," not "full match," semantics a bare `RegExp.prototype.test()` call has without the `^.../$...` anchors pinning it down, since `^`/`$` are already ordinary states inside the automaton (see `nfa.ts`) rather than a separate mode this function chooses between.
+*
+* The technique is the standard "add a fresh thread at every position" Thompson NFA search (Cox, "Regular Expression Matching Can Be Simple And Fast"): a new candidate match start is injected into the active state set before each character is consumed, exactly as if `.*?` had been prepended to an anchored pattern, except no such prefix is ever built -- the injection is the runtime equivalent of it. Because injection happens unconditionally and `^`'s own position check is what actually restricts where a match may begin, a pattern beginning with `^` still only ever matches from position 0, and one that does not can begin anywhere.
+*
+* Runs in O(length x states) time and allocates no more than two small state sets at a time, regardless of the pattern's shape -- there is no exponential blow-up for any input this compiles, which is the whole reason this package builds an automaton instead of calling a backtracking engine.
+*/
+function matchesNfa(nfa, input) {
+	const length = input.length;
+	let current = closure(nfa, [nfa.start], 0, length);
+	if (current.has(nfa.matchState)) return true;
+	for (let pos = 0; pos < length; pos += 1) {
+		const codeUnit = input.charCodeAt(pos);
+		const stepped = step(nfa, current, codeUnit);
+		stepped.add(nfa.start);
+		current = closure(nfa, [...stepped], pos + 1, length);
+		if (current.has(nfa.matchState)) return true;
+	}
+	return false;
+}
+/**
+* Parses `pattern` (this package's grammar; see README.md) and compiles it to a reference matcher.
+*
+* Prefer this over `testPattern` when the same pattern will be tested against more than one input: it parses and compiles exactly once, and the returned `CompiledPattern.test` is then only the O(length x states) simulation.
+*
+* @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+*/
+function compilePattern(pattern) {
+	const nfa = compileToNfa(parseRegex(pattern));
+	return { test: (input) => matchesNfa(nfa, input) };
+}
+/**
+* Parses `pattern` and tests it against `input` in one call. Equivalent to `compilePattern(pattern).test(input)`, and exactly as cheap for a single test -- prefer `compilePattern` instead when the same pattern will be reused, so the parse and compile steps happen once rather than once per input.
+*
+* @throws {RegexParseError} if `pattern` is not a valid pattern in this grammar.
+*/
+function testPattern(pattern, input) {
+	return compilePattern(pattern).test(input);
+}
+//#endregion
+export { compilePattern, matchesNfa, testPattern };

package/dist/nfa.cjs

@@ -0,0 +1,246 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_ast = require("./ast.cjs");
+//#region src/nfa.ts
+/**
+* Thompson construction: each AST node compiles to a fragment with one entry state and a list of dangling exits, and a parent node patches its children's exits to point at whatever comes next once it knows what that is. This is the standard technique (Thompson 1968; see also Cox, "Regular Expression Matching Can Be Simple And Fast") specifically because it never needs to look ahead -- a fragment is complete and correct in isolation, and composition is always "point these exits here," which is what keeps construction linear in pattern size even for deeply nested alternation and repetition.
+*/
+var NfaBuilder = class {
+	states = [];
+	add(state) {
+		this.states.push(state);
+		return this.states.length - 1;
+	}
+	patch(targets, target) {
+		for (const patchTarget of targets) {
+			const state = this.states[patchTarget.state];
+			if (state === void 0) continue;
+			switch (patchTarget.field) {
+				case "to":
+					if (state.kind === "char" || state.kind === "anchorStart" || state.kind === "anchorEnd") state.to = target;
+					break;
+				case "to1":
+					if (state.kind === "split") state.to1 = target;
+					break;
+				case "to2": if (state.kind === "split") state.to2 = target;
+			}
+		}
+	}
+	/** A fragment that matches the empty string unconditionally: both of a split's own branches dangle straight out, so whichever target they are later patched to is reached having consumed nothing. Used for `{0}`/`{0,0}` repetition, the one shape bounded repetition can produce that no other node kind already covers. */
+	emptyFrag() {
+		const idx = this.add({
+			kind: "split",
+			to1: -1,
+			to2: -1
+		});
+		return {
+			start: idx,
+			out: [{
+				state: idx,
+				field: "to1"
+			}, {
+				state: idx,
+				field: "to2"
+			}]
+		};
+	}
+	compileRepeat(node) {
+		const { operand, min, max } = node;
+		if (max === void 0) {
+			if (min === 0) return this.compileNode({
+				kind: "star",
+				operand
+			});
+			const parts = [];
+			for (let i = 0; i < min - 1; i += 1) parts.push(operand);
+			parts.push({
+				kind: "plus",
+				operand
+			});
+			return this.compileNode({
+				kind: "concat",
+				operands: parts
+			});
+		}
+		const parts = [];
+		for (let i = 0; i < min; i += 1) parts.push(operand);
+		for (let i = 0; i < max - min; i += 1) parts.push({
+			kind: "optional",
+			operand
+		});
+		if (parts.length === 0) return this.emptyFrag();
+		return this.compileNode({
+			kind: "concat",
+			operands: parts
+		});
+	}
+	compileNode(node) {
+		switch (node.kind) {
+			case "literal": {
+				const codeUnit = node.codeUnit;
+				const idx = this.add({
+					kind: "char",
+					test: (unit) => unit === codeUnit,
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anyChar": {
+				const idx = this.add({
+					kind: "char",
+					test: () => true,
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "charClass": {
+				const idx = this.add({
+					kind: "char",
+					test: (unit) => require_ast.charClassMatches(node, unit),
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anchorStart": {
+				const idx = this.add({
+					kind: "anchorStart",
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anchorEnd": {
+				const idx = this.add({
+					kind: "anchorEnd",
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "concat": {
+				if (node.operands.length === 0) return this.emptyFrag();
+				const [first, ...rest] = node.operands;
+				if (first === void 0) throw new Error("unreachable: a non-empty operands array always has a first element");
+				let frag = this.compileNode(first);
+				for (const operand of rest) {
+					const next = this.compileNode(operand);
+					this.patch(frag.out, next.start);
+					frag = {
+						start: frag.start,
+						out: next.out
+					};
+				}
+				return frag;
+			}
+			case "alternation": {
+				const [first, ...rest] = node.branches;
+				if (first === void 0) throw new Error("unreachable: AlternationNode always has at least two branches");
+				let frag = this.compileNode(first);
+				for (const branch of rest) {
+					const next = this.compileNode(branch);
+					frag = {
+						start: this.add({
+							kind: "split",
+							to1: frag.start,
+							to2: next.start
+						}),
+						out: [...frag.out, ...next.out]
+					};
+				}
+				return frag;
+			}
+			case "star": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				this.patch(inner.out, splitIdx);
+				return {
+					start: splitIdx,
+					out: [{
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "plus": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				this.patch(inner.out, splitIdx);
+				return {
+					start: inner.start,
+					out: [{
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "optional": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				return {
+					start: splitIdx,
+					out: [...inner.out, {
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "repeat": return this.compileRepeat(node);
+			default: throw new Error("unreachable regex node kind");
+		}
+	}
+	build(root) {
+		const frag = this.compileNode(root);
+		const matchState = this.add({ kind: "match" });
+		this.patch(frag.out, matchState);
+		return {
+			states: this.states,
+			start: frag.start,
+			matchState
+		};
+	}
+};
+/** Compiles a `RegexNode` AST into a Thompson-construction NFA, ready for `matchesNfa` (see `matcher.ts`) to simulate. Construction is linear in the size of the AST -- bounded repetition is the only node kind that can multiply state count beyond that, by exactly the multiple its own bound names, which is a property of what `{n,m}` means rather than of this algorithm. */
+function compileToNfa(node) {
+	return new NfaBuilder().build(node);
+}
+//#endregion
+exports.compileToNfa = compileToNfa;

package/dist/nfa.d.cts

@@ -0,0 +1,34 @@
+import { d as RegexNode } from "./ast-D8HLFxxv.cjs";
+//#region src/nfa.d.ts
+type CharTest = (codeUnit: number) => boolean;
+/**
+ * One state of the compiled automaton. `char` is the only kind that consumes input; every other kind is resolved away during epsilon-closure (see `closure` in `matcher.ts`) before a position is ever tested against an input character.
+ *
+ * `anchorStart`/`anchorEnd` are what let `^`/`$` live anywhere in the pattern -- inside a group, inside an alternation branch -- rather than only at the very start or end of the whole pattern text: they are ordinary epsilon transitions that the closure walk additionally gates on the absolute string position, so `^`'s condition ("this position is index 0 of the whole input") is checked at the moment the automaton would step through it, not baked into where `^` was allowed to appear syntactically.
+ */
+type NfaState = {
+  kind: "char";
+  test: CharTest;
+  to: number;
+} | {
+  kind: "split";
+  to1: number;
+  to2: number;
+} | {
+  kind: "anchorStart";
+  to: number;
+} | {
+  kind: "anchorEnd";
+  to: number;
+} | {
+  kind: "match";
+};
+interface CompiledNfa {
+  readonly states: readonly NfaState[];
+  readonly start: number;
+  readonly matchState: number;
+}
+/** Compiles a `RegexNode` AST into a Thompson-construction NFA, ready for `matchesNfa` (see `matcher.ts`) to simulate. Construction is linear in the size of the AST -- bounded repetition is the only node kind that can multiply state count beyond that, by exactly the multiple its own bound names, which is a property of what `{n,m}` means rather than of this algorithm. */
+declare function compileToNfa(node: RegexNode): CompiledNfa;
+//#endregion
+export { CompiledNfa, NfaState, compileToNfa };

package/dist/nfa.d.ts

@@ -0,0 +1,34 @@
+import { d as RegexNode } from "./ast-D8HLFxxv.js";
+//#region src/nfa.d.ts
+type CharTest = (codeUnit: number) => boolean;
+/**
+ * One state of the compiled automaton. `char` is the only kind that consumes input; every other kind is resolved away during epsilon-closure (see `closure` in `matcher.ts`) before a position is ever tested against an input character.
+ *
+ * `anchorStart`/`anchorEnd` are what let `^`/`$` live anywhere in the pattern -- inside a group, inside an alternation branch -- rather than only at the very start or end of the whole pattern text: they are ordinary epsilon transitions that the closure walk additionally gates on the absolute string position, so `^`'s condition ("this position is index 0 of the whole input") is checked at the moment the automaton would step through it, not baked into where `^` was allowed to appear syntactically.
+ */
+type NfaState = {
+  kind: "char";
+  test: CharTest;
+  to: number;
+} | {
+  kind: "split";
+  to1: number;
+  to2: number;
+} | {
+  kind: "anchorStart";
+  to: number;
+} | {
+  kind: "anchorEnd";
+  to: number;
+} | {
+  kind: "match";
+};
+interface CompiledNfa {
+  readonly states: readonly NfaState[];
+  readonly start: number;
+  readonly matchState: number;
+}
+/** Compiles a `RegexNode` AST into a Thompson-construction NFA, ready for `matchesNfa` (see `matcher.ts`) to simulate. Construction is linear in the size of the AST -- bounded repetition is the only node kind that can multiply state count beyond that, by exactly the multiple its own bound names, which is a property of what `{n,m}` means rather than of this algorithm. */
+declare function compileToNfa(node: RegexNode): CompiledNfa;
+//#endregion
+export { CompiledNfa, NfaState, compileToNfa };

package/dist/nfa.js

@@ -0,0 +1,245 @@
+import { charClassMatches } from "./ast.js";
+//#region src/nfa.ts
+/**
+* Thompson construction: each AST node compiles to a fragment with one entry state and a list of dangling exits, and a parent node patches its children's exits to point at whatever comes next once it knows what that is. This is the standard technique (Thompson 1968; see also Cox, "Regular Expression Matching Can Be Simple And Fast") specifically because it never needs to look ahead -- a fragment is complete and correct in isolation, and composition is always "point these exits here," which is what keeps construction linear in pattern size even for deeply nested alternation and repetition.
+*/
+var NfaBuilder = class {
+	states = [];
+	add(state) {
+		this.states.push(state);
+		return this.states.length - 1;
+	}
+	patch(targets, target) {
+		for (const patchTarget of targets) {
+			const state = this.states[patchTarget.state];
+			if (state === void 0) continue;
+			switch (patchTarget.field) {
+				case "to":
+					if (state.kind === "char" || state.kind === "anchorStart" || state.kind === "anchorEnd") state.to = target;
+					break;
+				case "to1":
+					if (state.kind === "split") state.to1 = target;
+					break;
+				case "to2": if (state.kind === "split") state.to2 = target;
+			}
+		}
+	}
+	/** A fragment that matches the empty string unconditionally: both of a split's own branches dangle straight out, so whichever target they are later patched to is reached having consumed nothing. Used for `{0}`/`{0,0}` repetition, the one shape bounded repetition can produce that no other node kind already covers. */
+	emptyFrag() {
+		const idx = this.add({
+			kind: "split",
+			to1: -1,
+			to2: -1
+		});
+		return {
+			start: idx,
+			out: [{
+				state: idx,
+				field: "to1"
+			}, {
+				state: idx,
+				field: "to2"
+			}]
+		};
+	}
+	compileRepeat(node) {
+		const { operand, min, max } = node;
+		if (max === void 0) {
+			if (min === 0) return this.compileNode({
+				kind: "star",
+				operand
+			});
+			const parts = [];
+			for (let i = 0; i < min - 1; i += 1) parts.push(operand);
+			parts.push({
+				kind: "plus",
+				operand
+			});
+			return this.compileNode({
+				kind: "concat",
+				operands: parts
+			});
+		}
+		const parts = [];
+		for (let i = 0; i < min; i += 1) parts.push(operand);
+		for (let i = 0; i < max - min; i += 1) parts.push({
+			kind: "optional",
+			operand
+		});
+		if (parts.length === 0) return this.emptyFrag();
+		return this.compileNode({
+			kind: "concat",
+			operands: parts
+		});
+	}
+	compileNode(node) {
+		switch (node.kind) {
+			case "literal": {
+				const codeUnit = node.codeUnit;
+				const idx = this.add({
+					kind: "char",
+					test: (unit) => unit === codeUnit,
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anyChar": {
+				const idx = this.add({
+					kind: "char",
+					test: () => true,
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "charClass": {
+				const idx = this.add({
+					kind: "char",
+					test: (unit) => charClassMatches(node, unit),
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anchorStart": {
+				const idx = this.add({
+					kind: "anchorStart",
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "anchorEnd": {
+				const idx = this.add({
+					kind: "anchorEnd",
+					to: -1
+				});
+				return {
+					start: idx,
+					out: [{
+						state: idx,
+						field: "to"
+					}]
+				};
+			}
+			case "concat": {
+				if (node.operands.length === 0) return this.emptyFrag();
+				const [first, ...rest] = node.operands;
+				if (first === void 0) throw new Error("unreachable: a non-empty operands array always has a first element");
+				let frag = this.compileNode(first);
+				for (const operand of rest) {
+					const next = this.compileNode(operand);
+					this.patch(frag.out, next.start);
+					frag = {
+						start: frag.start,
+						out: next.out
+					};
+				}
+				return frag;
+			}
+			case "alternation": {
+				const [first, ...rest] = node.branches;
+				if (first === void 0) throw new Error("unreachable: AlternationNode always has at least two branches");
+				let frag = this.compileNode(first);
+				for (const branch of rest) {
+					const next = this.compileNode(branch);
+					frag = {
+						start: this.add({
+							kind: "split",
+							to1: frag.start,
+							to2: next.start
+						}),
+						out: [...frag.out, ...next.out]
+					};
+				}
+				return frag;
+			}
+			case "star": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				this.patch(inner.out, splitIdx);
+				return {
+					start: splitIdx,
+					out: [{
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "plus": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				this.patch(inner.out, splitIdx);
+				return {
+					start: inner.start,
+					out: [{
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "optional": {
+				const inner = this.compileNode(node.operand);
+				const splitIdx = this.add({
+					kind: "split",
+					to1: inner.start,
+					to2: -1
+				});
+				return {
+					start: splitIdx,
+					out: [...inner.out, {
+						state: splitIdx,
+						field: "to2"
+					}]
+				};
+			}
+			case "repeat": return this.compileRepeat(node);
+			default: throw new Error("unreachable regex node kind");
+		}
+	}
+	build(root) {
+		const frag = this.compileNode(root);
+		const matchState = this.add({ kind: "match" });
+		this.patch(frag.out, matchState);
+		return {
+			states: this.states,
+			start: frag.start,
+			matchState
+		};
+	}
+};
+/** Compiles a `RegexNode` AST into a Thompson-construction NFA, ready for `matchesNfa` (see `matcher.ts`) to simulate. Construction is linear in the size of the AST -- bounded repetition is the only node kind that can multiply state count beyond that, by exactly the multiple its own bound names, which is a property of what `{n,m}` means rather than of this algorithm. */
+function compileToNfa(node) {
+	return new NfaBuilder().build(node);
+}
+//#endregion
+export { compileToNfa };