trilean-regex 0.0.0 → 1.0.1

package/dist/parser.cjs

@@ -0,0 +1,329 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("./errors.cjs");
+const require_shorthand_classes = require("./shorthand-classes.cjs");
+//#region src/parser.ts
+/** Characters that end the current alternation branch: the branch separator itself, and the group closer, at whichever level `parseSequence` is currently reading. Encountering either at the top level, with no matching opener, is the caller's job to reject -- `parseSequence` simply stops, leaving it for the enclosing `parseAlternation`/`parseGroup`/top-level `parseRegex` to notice. */
+const SEQUENCE_TERMINATORS = /* @__PURE__ */ new Set(["|", ")"]);
+const SIMPLE_ESCAPES = {
+	".": ".",
+	"*": "*",
+	"+": "+",
+	"?": "?",
+	"(": "(",
+	")": ")",
+	"[": "[",
+	"]": "]",
+	"{": "{",
+	"}": "}",
+	"|": "|",
+	"^": "^",
+	$: "$",
+	"\\": "\\",
+	"/": "/",
+	n: "\n",
+	t: "	",
+	r: "\r",
+	f: "\f",
+	v: "\v"
+};
+/**
+* Recursive-descent parser for the grammar documented in README.md. Each `parse*` method consumes exactly the construct it names and leaves `pos` positioned just past it; nothing here backtracks except the two speculative lookaheads (`tryParseBound`'s failure path, and `peekIsQuantifierStart`'s use of it), both of which restore `pos` themselves before returning.
+*
+* Holds no state beyond the source string and a cursor into it -- there is no token stream, no separate lexer pass. A character's meaning (metachar, literal, escape) is always decided in the context that is reading it (atom position, inside a class, right after a backslash), which is what a hand-written recursive-descent parser buys over a generic lexer/parser split for a grammar this size.
+*/
+var Parser = class {
+	pattern;
+	pos = 0;
+	constructor(pattern) {
+		this.pattern = pattern;
+	}
+	get position() {
+		return this.pos;
+	}
+	atEnd() {
+		return this.pos >= this.pattern.length;
+	}
+	peek(offset = 0) {
+		return this.pattern[this.pos + offset];
+	}
+	advance() {
+		const char = this.pattern[this.pos];
+		if (char === void 0) throw new require_errors.RegexParseError(this.pattern, this.pos, "unexpected end of pattern");
+		this.pos += 1;
+		return char;
+	}
+	parseAlternation() {
+		const firstBranch = this.parseSequence();
+		const laterBranches = [];
+		while (this.peek() === "|") {
+			this.advance();
+			laterBranches.push(this.parseSequence());
+		}
+		return laterBranches.length === 0 ? firstBranch : {
+			kind: "alternation",
+			branches: [firstBranch, ...laterBranches]
+		};
+	}
+	parseSequence() {
+		if (this.atEnd() || SEQUENCE_TERMINATORS.has(this.peek() ?? "")) return {
+			kind: "concat",
+			operands: []
+		};
+		const firstOperand = this.parseQuantified();
+		const laterOperands = [];
+		while (!this.atEnd() && !SEQUENCE_TERMINATORS.has(this.peek() ?? "")) laterOperands.push(this.parseQuantified());
+		return laterOperands.length === 0 ? firstOperand : {
+			kind: "concat",
+			operands: [firstOperand, ...laterOperands]
+		};
+	}
+	parseQuantified() {
+		const atomStart = this.pos;
+		const atom = this.parseAtom();
+		if (atom.kind === "anchorStart" || atom.kind === "anchorEnd") {
+			if (this.peekIsQuantifierStart()) throw new require_errors.RegexParseError(this.pattern, atomStart, `an anchor ('${atom.kind === "anchorStart" ? "^" : "$"}') cannot be quantified`);
+			return atom;
+		}
+		const quantifier = this.tryParseQuantifier();
+		if (quantifier === void 0) return atom;
+		if (this.peekIsQuantifierStart()) throw new require_errors.RegexParseError(this.pattern, this.pos, "a quantifier cannot itself be quantified -- this grammar has no lazy or possessive modifiers, since a pattern that only ever answers a yes/no match question has no notion for either to change");
+		switch (quantifier.kind) {
+			case "star": return {
+				kind: "star",
+				operand: atom
+			};
+			case "plus": return {
+				kind: "plus",
+				operand: atom
+			};
+			case "optional": return {
+				kind: "optional",
+				operand: atom
+			};
+			case "repeat": return {
+				kind: "repeat",
+				operand: atom,
+				min: quantifier.min,
+				max: quantifier.max
+			};
+			default: throw new Error("unreachable quantifier kind");
+		}
+	}
+	/** A pure lookahead: restores `pos` before returning in every case, including through `tryParseBound`'s own successful parse. Used only to decide whether a second quantifier immediately follows the one just applied, which is always a parse error (see `parseQuantified`). */
+	peekIsQuantifierStart() {
+		const c = this.peek();
+		if (c === "*" || c === "+" || c === "?") return true;
+		if (c === "{") {
+			const savedPos = this.pos;
+			const bound = this.tryParseBound();
+			this.pos = savedPos;
+			return bound !== void 0;
+		}
+		return false;
+	}
+	tryParseQuantifier() {
+		const c = this.peek();
+		if (c === "*") {
+			this.advance();
+			return { kind: "star" };
+		}
+		if (c === "+") {
+			this.advance();
+			return { kind: "plus" };
+		}
+		if (c === "?") {
+			this.advance();
+			return { kind: "optional" };
+		}
+		if (c === "{") {
+			const bound = this.tryParseBound();
+			if (bound === void 0) return void 0;
+			return {
+				kind: "repeat",
+				min: bound.min,
+				max: bound.max
+			};
+		}
+	}
+	/**
+	* Attempts `{min}` / `{min,}` / `{min,max}` starting at the current `{`. Rewinds and returns `undefined` for anything that is not exactly one of those three shapes -- including `{}`, `{,5}`, and a `{` with no closing brace at all -- so that an unrecognised `{` falls back to being parsed as a literal character by the caller, matching how a bounded-repetition quantifier is conventionally the only special meaning `{` ever carries.
+	*
+	* A backwards bound (`{5,2}`) is a real error rather than a fallback-to-literal case: the syntax is unambiguously a quantifier attempt, so this throws instead of returning `undefined` for it.
+	*/
+	tryParseBound() {
+		const savedPos = this.pos;
+		this.pos += 1;
+		const minDigits = this.readDigits();
+		if (minDigits === "") {
+			this.pos = savedPos;
+			return;
+		}
+		let maxDigits;
+		let hasComma = false;
+		if (this.peek() === ",") {
+			hasComma = true;
+			this.pos += 1;
+			maxDigits = this.readDigits();
+		}
+		if (this.peek() !== "}") {
+			this.pos = savedPos;
+			return;
+		}
+		this.pos += 1;
+		const min = Number.parseInt(minDigits, 10);
+		const max = !hasComma ? min : maxDigits === "" ? void 0 : Number.parseInt(maxDigits ?? "", 10);
+		if (max !== void 0 && max < min) throw new require_errors.RegexParseError(this.pattern, savedPos, `quantifier range is backwards: {${minDigits}${hasComma ? "," + (maxDigits ?? "") : ""}} would require between ${String(min)} and ${String(max)} repetitions`);
+		return {
+			min,
+			max
+		};
+	}
+	readDigits() {
+		let digits = "";
+		for (;;) {
+			const c = this.peek();
+			if (c === void 0 || c < "0" || c > "9") break;
+			digits += c;
+			this.pos += 1;
+		}
+		return digits;
+	}
+	parseAtom() {
+		const c = this.peek();
+		if (c === void 0) throw new require_errors.RegexParseError(this.pattern, this.pos, "unexpected end of pattern");
+		if (c === "^") {
+			this.advance();
+			return { kind: "anchorStart" };
+		}
+		if (c === "$") {
+			this.advance();
+			return { kind: "anchorEnd" };
+		}
+		if (c === ".") {
+			this.advance();
+			return { kind: "anyChar" };
+		}
+		if (c === "(") return this.parseGroup();
+		if (c === "[") return this.parseCharClass();
+		if (c === "\\") return this.parseEscapedAtom();
+		if (c === "*" || c === "+" || c === "?") throw new require_errors.RegexParseError(this.pattern, this.pos, `quantifier '${c}' with nothing to repeat`);
+		this.advance();
+		return {
+			kind: "literal",
+			codeUnit: c.charCodeAt(0)
+		};
+	}
+	parseGroup() {
+		const start = this.pos;
+		this.advance();
+		if (this.peek() === "?" && this.peek(1) === ":") {
+			this.advance();
+			this.advance();
+		} else throw new require_errors.RegexParseError(this.pattern, start, "capturing groups are not supported in this grammar -- there is nothing to capture, since a pattern only ever answers whether it matches. Use '(?:...)' for grouping.");
+		const inner = this.parseAlternation();
+		if (this.peek() !== ")") throw new require_errors.RegexParseError(this.pattern, this.pos, "expected ')' to close '(?:'");
+		this.advance();
+		return inner;
+	}
+	parseEscapedAtom() {
+		const backslashPos = this.pos;
+		this.advance();
+		if (this.atEnd()) throw new require_errors.RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+		const c = this.advance();
+		if (c === "d" || c === "D" || c === "w" || c === "W" || c === "s" || c === "S") return require_shorthand_classes.expandShorthandClass(c);
+		const literal = SIMPLE_ESCAPES[c];
+		if (literal !== void 0) return {
+			kind: "literal",
+			codeUnit: literal.charCodeAt(0)
+		};
+		throw new require_errors.RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${c}'`);
+	}
+	parseCharClass() {
+		const start = this.pos;
+		this.advance();
+		let negated = false;
+		if (this.peek() === "^") {
+			this.advance();
+			negated = true;
+		}
+		const ranges = [];
+		for (;;) {
+			if (this.atEnd()) throw new require_errors.RegexParseError(this.pattern, start, "unterminated character class -- missing closing ']'");
+			if (this.peek() === "]") {
+				if (ranges.length === 0) throw new require_errors.RegexParseError(this.pattern, this.pos, "a character class must contain at least one item -- ']' immediately, or immediately after '[^', is not the empty class here (escape it as '\\]' to match a literal ']')");
+				this.advance();
+				break;
+			}
+			ranges.push(...this.parseClassItem());
+		}
+		return {
+			kind: "charClass",
+			negated,
+			ranges
+		};
+	}
+	parseClassItem() {
+		const c = this.peek();
+		if (c === "\\") {
+			const backslashPos = this.pos;
+			this.advance();
+			if (this.atEnd()) throw new require_errors.RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+			const escaped = this.advance();
+			if (escaped === "d" || escaped === "w" || escaped === "s") return require_shorthand_classes.expandShorthandClass(escaped).ranges;
+			if (escaped === "D" || escaped === "W" || escaped === "S") throw new require_errors.RegexParseError(this.pattern, backslashPos, `the negated shorthand class '\\${escaped}' cannot be embedded inside a character class, because its complement cannot be represented as a set of ranges to union with the class's other members -- use it as its own atom instead of embedding it here`);
+			const literal = SIMPLE_ESCAPES[escaped];
+			if (literal === void 0) throw new require_errors.RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${escaped}'`);
+			return this.parseOptionalRangeFrom(literal.charCodeAt(0));
+		}
+		if (c === void 0) throw new require_errors.RegexParseError(this.pattern, this.pos, "unterminated character class -- missing closing ']'");
+		this.advance();
+		return this.parseOptionalRangeFrom(c.charCodeAt(0));
+	}
+	parseOptionalRangeFrom(fromCode) {
+		if (this.peek() === "-" && this.peek(1) !== void 0 && this.peek(1) !== "]") {
+			const hyphenPos = this.pos;
+			this.advance();
+			const toCode = this.parseClassRangeEndpoint();
+			if (toCode < fromCode) throw new require_errors.RegexParseError(this.pattern, hyphenPos, `invalid range in character class: '${String.fromCharCode(fromCode)}-${String.fromCharCode(toCode)}' is reversed`);
+			return [{
+				from: fromCode,
+				to: toCode
+			}];
+		}
+		return [{
+			from: fromCode,
+			to: fromCode
+		}];
+	}
+	parseClassRangeEndpoint() {
+		const c = this.peek();
+		if (c === "\\") {
+			const backslashPos = this.pos;
+			this.advance();
+			if (this.atEnd()) throw new require_errors.RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+			const escaped = this.advance();
+			if (escaped === "d" || escaped === "D" || escaped === "w" || escaped === "W" || escaped === "s" || escaped === "S") throw new require_errors.RegexParseError(this.pattern, backslashPos, `a shorthand class ('\\${escaped}') cannot be a range endpoint`);
+			const literal = SIMPLE_ESCAPES[escaped];
+			if (literal === void 0) throw new require_errors.RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${escaped}'`);
+			return literal.charCodeAt(0);
+		}
+		if (c === void 0) throw new require_errors.RegexParseError(this.pattern, this.pos, "unterminated character class -- missing closing ']'");
+		this.advance();
+		return c.charCodeAt(0);
+	}
+};
+/**
+* Parses a pattern in this package's grammar (see README.md) into a `RegexNode` AST.
+*
+* Never returns a partial result: a pattern either parses completely, with nothing left over, or this throws `RegexParseError` naming exactly where parsing could not proceed.
+*
+* @throws {RegexParseError} if `pattern` is not a complete, valid pattern in this grammar.
+*/
+function parseRegex(pattern) {
+	const parser = new Parser(pattern);
+	const node = parser.parseAlternation();
+	if (!parser.atEnd()) throw new require_errors.RegexParseError(pattern, parser.position, "unexpected character -- if this was meant literally, escape it with a backslash");
+	return node;
+}
+//#endregion
+exports.parseRegex = parseRegex;

package/dist/parser.d.cts

@@ -0,0 +1,12 @@
+import { d as RegexNode } from "./ast-D8HLFxxv.cjs";
+//#region src/parser.d.ts
+/**
+ * Parses a pattern in this package's grammar (see README.md) into a `RegexNode` AST.
+ *
+ * Never returns a partial result: a pattern either parses completely, with nothing left over, or this throws `RegexParseError` naming exactly where parsing could not proceed.
+ *
+ * @throws {RegexParseError} if `pattern` is not a complete, valid pattern in this grammar.
+ */
+declare function parseRegex(pattern: string): RegexNode;
+//#endregion
+export { parseRegex };

package/dist/parser.d.ts

@@ -0,0 +1,12 @@
+import { d as RegexNode } from "./ast-D8HLFxxv.js";
+//#region src/parser.d.ts
+/**
+ * Parses a pattern in this package's grammar (see README.md) into a `RegexNode` AST.
+ *
+ * Never returns a partial result: a pattern either parses completely, with nothing left over, or this throws `RegexParseError` naming exactly where parsing could not proceed.
+ *
+ * @throws {RegexParseError} if `pattern` is not a complete, valid pattern in this grammar.
+ */
+declare function parseRegex(pattern: string): RegexNode;
+//#endregion
+export { parseRegex };

package/dist/parser.js

@@ -0,0 +1,328 @@
+import { RegexParseError } from "./errors.js";
+import { expandShorthandClass } from "./shorthand-classes.js";
+//#region src/parser.ts
+/** Characters that end the current alternation branch: the branch separator itself, and the group closer, at whichever level `parseSequence` is currently reading. Encountering either at the top level, with no matching opener, is the caller's job to reject -- `parseSequence` simply stops, leaving it for the enclosing `parseAlternation`/`parseGroup`/top-level `parseRegex` to notice. */
+const SEQUENCE_TERMINATORS = /* @__PURE__ */ new Set(["|", ")"]);
+const SIMPLE_ESCAPES = {
+	".": ".",
+	"*": "*",
+	"+": "+",
+	"?": "?",
+	"(": "(",
+	")": ")",
+	"[": "[",
+	"]": "]",
+	"{": "{",
+	"}": "}",
+	"|": "|",
+	"^": "^",
+	$: "$",
+	"\\": "\\",
+	"/": "/",
+	n: "\n",
+	t: "	",
+	r: "\r",
+	f: "\f",
+	v: "\v"
+};
+/**
+* Recursive-descent parser for the grammar documented in README.md. Each `parse*` method consumes exactly the construct it names and leaves `pos` positioned just past it; nothing here backtracks except the two speculative lookaheads (`tryParseBound`'s failure path, and `peekIsQuantifierStart`'s use of it), both of which restore `pos` themselves before returning.
+*
+* Holds no state beyond the source string and a cursor into it -- there is no token stream, no separate lexer pass. A character's meaning (metachar, literal, escape) is always decided in the context that is reading it (atom position, inside a class, right after a backslash), which is what a hand-written recursive-descent parser buys over a generic lexer/parser split for a grammar this size.
+*/
+var Parser = class {
+	pattern;
+	pos = 0;
+	constructor(pattern) {
+		this.pattern = pattern;
+	}
+	get position() {
+		return this.pos;
+	}
+	atEnd() {
+		return this.pos >= this.pattern.length;
+	}
+	peek(offset = 0) {
+		return this.pattern[this.pos + offset];
+	}
+	advance() {
+		const char = this.pattern[this.pos];
+		if (char === void 0) throw new RegexParseError(this.pattern, this.pos, "unexpected end of pattern");
+		this.pos += 1;
+		return char;
+	}
+	parseAlternation() {
+		const firstBranch = this.parseSequence();
+		const laterBranches = [];
+		while (this.peek() === "|") {
+			this.advance();
+			laterBranches.push(this.parseSequence());
+		}
+		return laterBranches.length === 0 ? firstBranch : {
+			kind: "alternation",
+			branches: [firstBranch, ...laterBranches]
+		};
+	}
+	parseSequence() {
+		if (this.atEnd() || SEQUENCE_TERMINATORS.has(this.peek() ?? "")) return {
+			kind: "concat",
+			operands: []
+		};
+		const firstOperand = this.parseQuantified();
+		const laterOperands = [];
+		while (!this.atEnd() && !SEQUENCE_TERMINATORS.has(this.peek() ?? "")) laterOperands.push(this.parseQuantified());
+		return laterOperands.length === 0 ? firstOperand : {
+			kind: "concat",
+			operands: [firstOperand, ...laterOperands]
+		};
+	}
+	parseQuantified() {
+		const atomStart = this.pos;
+		const atom = this.parseAtom();
+		if (atom.kind === "anchorStart" || atom.kind === "anchorEnd") {
+			if (this.peekIsQuantifierStart()) throw new RegexParseError(this.pattern, atomStart, `an anchor ('${atom.kind === "anchorStart" ? "^" : "$"}') cannot be quantified`);
+			return atom;
+		}
+		const quantifier = this.tryParseQuantifier();
+		if (quantifier === void 0) return atom;
+		if (this.peekIsQuantifierStart()) throw new RegexParseError(this.pattern, this.pos, "a quantifier cannot itself be quantified -- this grammar has no lazy or possessive modifiers, since a pattern that only ever answers a yes/no match question has no notion for either to change");
+		switch (quantifier.kind) {
+			case "star": return {
+				kind: "star",
+				operand: atom
+			};
+			case "plus": return {
+				kind: "plus",
+				operand: atom
+			};
+			case "optional": return {
+				kind: "optional",
+				operand: atom
+			};
+			case "repeat": return {
+				kind: "repeat",
+				operand: atom,
+				min: quantifier.min,
+				max: quantifier.max
+			};
+			default: throw new Error("unreachable quantifier kind");
+		}
+	}
+	/** A pure lookahead: restores `pos` before returning in every case, including through `tryParseBound`'s own successful parse. Used only to decide whether a second quantifier immediately follows the one just applied, which is always a parse error (see `parseQuantified`). */
+	peekIsQuantifierStart() {
+		const c = this.peek();
+		if (c === "*" || c === "+" || c === "?") return true;
+		if (c === "{") {
+			const savedPos = this.pos;
+			const bound = this.tryParseBound();
+			this.pos = savedPos;
+			return bound !== void 0;
+		}
+		return false;
+	}
+	tryParseQuantifier() {
+		const c = this.peek();
+		if (c === "*") {
+			this.advance();
+			return { kind: "star" };
+		}
+		if (c === "+") {
+			this.advance();
+			return { kind: "plus" };
+		}
+		if (c === "?") {
+			this.advance();
+			return { kind: "optional" };
+		}
+		if (c === "{") {
+			const bound = this.tryParseBound();
+			if (bound === void 0) return void 0;
+			return {
+				kind: "repeat",
+				min: bound.min,
+				max: bound.max
+			};
+		}
+	}
+	/**
+	* Attempts `{min}` / `{min,}` / `{min,max}` starting at the current `{`. Rewinds and returns `undefined` for anything that is not exactly one of those three shapes -- including `{}`, `{,5}`, and a `{` with no closing brace at all -- so that an unrecognised `{` falls back to being parsed as a literal character by the caller, matching how a bounded-repetition quantifier is conventionally the only special meaning `{` ever carries.
+	*
+	* A backwards bound (`{5,2}`) is a real error rather than a fallback-to-literal case: the syntax is unambiguously a quantifier attempt, so this throws instead of returning `undefined` for it.
+	*/
+	tryParseBound() {
+		const savedPos = this.pos;
+		this.pos += 1;
+		const minDigits = this.readDigits();
+		if (minDigits === "") {
+			this.pos = savedPos;
+			return;
+		}
+		let maxDigits;
+		let hasComma = false;
+		if (this.peek() === ",") {
+			hasComma = true;
+			this.pos += 1;
+			maxDigits = this.readDigits();
+		}
+		if (this.peek() !== "}") {
+			this.pos = savedPos;
+			return;
+		}
+		this.pos += 1;
+		const min = Number.parseInt(minDigits, 10);
+		const max = !hasComma ? min : maxDigits === "" ? void 0 : Number.parseInt(maxDigits ?? "", 10);
+		if (max !== void 0 && max < min) throw new RegexParseError(this.pattern, savedPos, `quantifier range is backwards: {${minDigits}${hasComma ? "," + (maxDigits ?? "") : ""}} would require between ${String(min)} and ${String(max)} repetitions`);
+		return {
+			min,
+			max
+		};
+	}
+	readDigits() {
+		let digits = "";
+		for (;;) {
+			const c = this.peek();
+			if (c === void 0 || c < "0" || c > "9") break;
+			digits += c;
+			this.pos += 1;
+		}
+		return digits;
+	}
+	parseAtom() {
+		const c = this.peek();
+		if (c === void 0) throw new RegexParseError(this.pattern, this.pos, "unexpected end of pattern");
+		if (c === "^") {
+			this.advance();
+			return { kind: "anchorStart" };
+		}
+		if (c === "$") {
+			this.advance();
+			return { kind: "anchorEnd" };
+		}
+		if (c === ".") {
+			this.advance();
+			return { kind: "anyChar" };
+		}
+		if (c === "(") return this.parseGroup();
+		if (c === "[") return this.parseCharClass();
+		if (c === "\\") return this.parseEscapedAtom();
+		if (c === "*" || c === "+" || c === "?") throw new RegexParseError(this.pattern, this.pos, `quantifier '${c}' with nothing to repeat`);
+		this.advance();
+		return {
+			kind: "literal",
+			codeUnit: c.charCodeAt(0)
+		};
+	}
+	parseGroup() {
+		const start = this.pos;
+		this.advance();
+		if (this.peek() === "?" && this.peek(1) === ":") {
+			this.advance();
+			this.advance();
+		} else throw new RegexParseError(this.pattern, start, "capturing groups are not supported in this grammar -- there is nothing to capture, since a pattern only ever answers whether it matches. Use '(?:...)' for grouping.");
+		const inner = this.parseAlternation();
+		if (this.peek() !== ")") throw new RegexParseError(this.pattern, this.pos, "expected ')' to close '(?:'");
+		this.advance();
+		return inner;
+	}
+	parseEscapedAtom() {
+		const backslashPos = this.pos;
+		this.advance();
+		if (this.atEnd()) throw new RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+		const c = this.advance();
+		if (c === "d" || c === "D" || c === "w" || c === "W" || c === "s" || c === "S") return expandShorthandClass(c);
+		const literal = SIMPLE_ESCAPES[c];
+		if (literal !== void 0) return {
+			kind: "literal",
+			codeUnit: literal.charCodeAt(0)
+		};
+		throw new RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${c}'`);
+	}
+	parseCharClass() {
+		const start = this.pos;
+		this.advance();
+		let negated = false;
+		if (this.peek() === "^") {
+			this.advance();
+			negated = true;
+		}
+		const ranges = [];
+		for (;;) {
+			if (this.atEnd()) throw new RegexParseError(this.pattern, start, "unterminated character class -- missing closing ']'");
+			if (this.peek() === "]") {
+				if (ranges.length === 0) throw new RegexParseError(this.pattern, this.pos, "a character class must contain at least one item -- ']' immediately, or immediately after '[^', is not the empty class here (escape it as '\\]' to match a literal ']')");
+				this.advance();
+				break;
+			}
+			ranges.push(...this.parseClassItem());
+		}
+		return {
+			kind: "charClass",
+			negated,
+			ranges
+		};
+	}
+	parseClassItem() {
+		const c = this.peek();
+		if (c === "\\") {
+			const backslashPos = this.pos;
+			this.advance();
+			if (this.atEnd()) throw new RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+			const escaped = this.advance();
+			if (escaped === "d" || escaped === "w" || escaped === "s") return expandShorthandClass(escaped).ranges;
+			if (escaped === "D" || escaped === "W" || escaped === "S") throw new RegexParseError(this.pattern, backslashPos, `the negated shorthand class '\\${escaped}' cannot be embedded inside a character class, because its complement cannot be represented as a set of ranges to union with the class's other members -- use it as its own atom instead of embedding it here`);
+			const literal = SIMPLE_ESCAPES[escaped];
+			if (literal === void 0) throw new RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${escaped}'`);
+			return this.parseOptionalRangeFrom(literal.charCodeAt(0));
+		}
+		if (c === void 0) throw new RegexParseError(this.pattern, this.pos, "unterminated character class -- missing closing ']'");
+		this.advance();
+		return this.parseOptionalRangeFrom(c.charCodeAt(0));
+	}
+	parseOptionalRangeFrom(fromCode) {
+		if (this.peek() === "-" && this.peek(1) !== void 0 && this.peek(1) !== "]") {
+			const hyphenPos = this.pos;
+			this.advance();
+			const toCode = this.parseClassRangeEndpoint();
+			if (toCode < fromCode) throw new RegexParseError(this.pattern, hyphenPos, `invalid range in character class: '${String.fromCharCode(fromCode)}-${String.fromCharCode(toCode)}' is reversed`);
+			return [{
+				from: fromCode,
+				to: toCode
+			}];
+		}
+		return [{
+			from: fromCode,
+			to: fromCode
+		}];
+	}
+	parseClassRangeEndpoint() {
+		const c = this.peek();
+		if (c === "\\") {
+			const backslashPos = this.pos;
+			this.advance();
+			if (this.atEnd()) throw new RegexParseError(this.pattern, backslashPos, "trailing backslash with nothing to escape");
+			const escaped = this.advance();
+			if (escaped === "d" || escaped === "D" || escaped === "w" || escaped === "W" || escaped === "s" || escaped === "S") throw new RegexParseError(this.pattern, backslashPos, `a shorthand class ('\\${escaped}') cannot be a range endpoint`);
+			const literal = SIMPLE_ESCAPES[escaped];
+			if (literal === void 0) throw new RegexParseError(this.pattern, backslashPos, `unknown escape sequence '\\${escaped}'`);
+			return literal.charCodeAt(0);
+		}
+		if (c === void 0) throw new RegexParseError(this.pattern, this.pos, "unterminated character class -- missing closing ']'");
+		this.advance();
+		return c.charCodeAt(0);
+	}
+};
+/**
+* Parses a pattern in this package's grammar (see README.md) into a `RegexNode` AST.
+*
+* Never returns a partial result: a pattern either parses completely, with nothing left over, or this throws `RegexParseError` naming exactly where parsing could not proceed.
+*
+* @throws {RegexParseError} if `pattern` is not a complete, valid pattern in this grammar.
+*/
+function parseRegex(pattern) {
+	const parser = new Parser(pattern);
+	const node = parser.parseAlternation();
+	if (!parser.atEnd()) throw new RegexParseError(pattern, parser.position, "unexpected character -- if this was meant literally, escape it with a backslash");
+	return node;
+}
+//#endregion
+export { parseRegex };