@optique/core 0.1.0-dev.1

package/dist/parser.cjs

@@ -0,0 +1,1065 @@
+const require_message = require('./message.cjs');
+const require_usage = require('./usage.cjs');
+const require_valueparser = require('./valueparser.cjs');
+
+//#region src/parser.ts
+/**
+* Creates a parser that always succeeds without consuming any input and
+* produces a constant value of the type {@link T}.
+* @template T The type of the constant value produced by the parser.
+*/
+function constant(value) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 0,
+		usage: [],
+		initialState: value,
+		parse(context) {
+			return {
+				success: true,
+				next: context,
+				consumed: []
+			};
+		},
+		complete(state) {
+			return {
+				success: true,
+				value: state
+			};
+		},
+		getDocFragments(_state, _defaultValue) {
+			return { fragments: [] };
+		}
+	};
+}
+function option(...args) {
+	const lastArg = args.at(-1);
+	const secondLastArg = args.at(-2);
+	let valueParser;
+	let optionNames$1;
+	let options = {};
+	if (require_valueparser.isValueParser(lastArg)) {
+		valueParser = lastArg;
+		optionNames$1 = args.slice(0, -1);
+	} else if (typeof lastArg === "object" && lastArg != null) {
+		options = lastArg;
+		if (require_valueparser.isValueParser(secondLastArg)) {
+			valueParser = secondLastArg;
+			optionNames$1 = args.slice(0, -2);
+		} else {
+			valueParser = void 0;
+			optionNames$1 = args.slice(0, -1);
+		}
+	} else {
+		optionNames$1 = args;
+		valueParser = void 0;
+	}
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 10,
+		usage: [valueParser == null ? {
+			type: "optional",
+			terms: [{
+				type: "option",
+				names: optionNames$1
+			}]
+		} : {
+			type: "option",
+			names: optionNames$1,
+			metavar: valueParser.metavar
+		}],
+		initialState: valueParser == null ? {
+			success: true,
+			value: false
+		} : {
+			success: false,
+			error: require_message.message`Missing option ${require_message.optionNames(optionNames$1)}.`
+		},
+		parse(context) {
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No more options can be parsed.`
+			};
+			else if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`Expected an option, but got end of input.`
+			};
+			if (context.buffer[0] === "--") return {
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(1),
+					state: context.state,
+					optionsTerminated: true
+				},
+				consumed: context.buffer.slice(0, 1)
+			};
+			if (optionNames$1.includes(context.buffer[0])) {
+				if (context.state.success && (valueParser != null || context.state.value)) return {
+					success: false,
+					consumed: 1,
+					error: require_message.message`${context.buffer[0]} cannot be used multiple times.`
+				};
+				if (valueParser == null) return {
+					success: true,
+					next: {
+						...context,
+						state: {
+							success: true,
+							value: true
+						},
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+				if (context.buffer.length < 2) return {
+					success: false,
+					consumed: 1,
+					error: require_message.message`Option ${require_message.optionName(context.buffer[0])} requires a value, but got no value.`
+				};
+				const result = valueParser.parse(context.buffer[1]);
+				return {
+					success: true,
+					next: {
+						...context,
+						state: result,
+						buffer: context.buffer.slice(2)
+					},
+					consumed: context.buffer.slice(0, 2)
+				};
+			}
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			for (const prefix of prefixes) {
+				if (!context.buffer[0].startsWith(prefix)) continue;
+				if (context.state.success && (valueParser != null || context.state.value)) return {
+					success: false,
+					consumed: 1,
+					error: require_message.message`${require_message.optionName(prefix)} cannot be used multiple times.`
+				};
+				const value = context.buffer[0].slice(prefix.length);
+				if (valueParser == null) return {
+					success: false,
+					consumed: 1,
+					error: require_message.message`Option ${require_message.optionName(prefix)} is a Boolean flag, but got a value: ${value}.`
+				};
+				const result = valueParser.parse(value);
+				return {
+					success: true,
+					next: {
+						...context,
+						state: result,
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+			}
+			if (valueParser == null) {
+				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
+				for (const shortOption of shortOptions) {
+					if (!context.buffer[0].startsWith(shortOption)) continue;
+					if (context.state.success && (valueParser != null || context.state.value)) return {
+						success: false,
+						consumed: 1,
+						error: require_message.message`${require_message.optionName(shortOption)} cannot be used multiple times.`
+					};
+					return {
+						success: true,
+						next: {
+							...context,
+							state: {
+								success: true,
+								value: true
+							},
+							buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
+						},
+						consumed: [context.buffer[0].slice(0, 2)]
+					};
+				}
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No matched option for ${require_message.optionName(context.buffer[0])}.`
+			};
+		},
+		complete(state) {
+			if (state == null) return valueParser == null ? {
+				success: true,
+				value: false
+			} : {
+				success: false,
+				error: require_message.message`Missing option ${require_message.optionNames(optionNames$1)}.`
+			};
+			if (state.success) return state;
+			return {
+				success: false,
+				error: require_message.message`${require_message.optionNames(optionNames$1)}: ${state.error}`
+			};
+		},
+		getDocFragments(_state, defaultValue) {
+			const fragments = [{
+				type: "entry",
+				term: {
+					type: "option",
+					names: optionNames$1,
+					metavar: valueParser?.metavar
+				},
+				description: options.description,
+				default: defaultValue != null && valueParser != null ? valueParser.format(defaultValue) : void 0
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
+		}
+	};
+}
+/**
+* Creates a parser that expects a single argument value.
+* This parser is typically used for positional arguments
+* that are not options or flags.
+* @template T The type of the value produced by the parser.
+* @param valueParser The {@link ValueParser} that defines how to parse
+*                    the argument value.
+* @param options Optional configuration for the argument parser,
+*                allowing you to specify a description or other metadata.
+* @returns A {@link Parser} that expects a single argument value and produces
+*          the parsed value of type {@link T}.
+*/
+function argument(valueParser, options = {}) {
+	const optionPattern = /^--?[a-z0-9-]+$/i;
+	const term = {
+		type: "argument",
+		metavar: valueParser.metavar
+	};
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 5,
+		usage: [term],
+		initialState: void 0,
+		parse(context) {
+			if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`Expected an argument, but got end of input.`
+			};
+			let i = 0;
+			let optionsTerminated = context.optionsTerminated;
+			if (!optionsTerminated) {
+				if (context.buffer[i] === "--") {
+					optionsTerminated = true;
+					i++;
+				} else if (context.buffer[i].match(optionPattern)) return {
+					success: false,
+					consumed: i,
+					error: require_message.message`Expected an argument, but got an option: ${require_message.optionName(context.buffer[i])}.`
+				};
+			}
+			if (context.buffer.length < i + 1) return {
+				success: false,
+				consumed: i,
+				error: require_message.message`Expected an argument, but got end of input.`
+			};
+			if (context.state != null) return {
+				success: false,
+				consumed: i,
+				error: require_message.message`The argument ${require_message.metavar(valueParser.metavar)} cannot be used multiple times.`
+			};
+			const result = valueParser.parse(context.buffer[i]);
+			return {
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(i + 1),
+					state: result,
+					optionsTerminated
+				},
+				consumed: context.buffer.slice(0, i + 1)
+			};
+		},
+		complete(state) {
+			if (state == null) return {
+				success: false,
+				error: require_message.message`Expected a ${require_message.metavar(valueParser.metavar)}, but too few arguments.`
+			};
+			else if (state.success) return state;
+			return {
+				success: false,
+				error: require_message.message`${require_message.metavar(valueParser.metavar)}: ${state.error}`
+			};
+		},
+		getDocFragments(_state, defaultValue) {
+			const fragments = [{
+				type: "entry",
+				term,
+				description: options.description,
+				default: defaultValue == null ? void 0 : valueParser.format(defaultValue)
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `argument()`;
+		}
+	};
+}
+/**
+* Creates a parser that makes another parser optional, allowing it to succeed
+* without consuming input if the wrapped parser fails to match.
+* If the wrapped parser succeeds, this returns its value.
+* If the wrapped parser fails, this returns `undefined` without consuming input.
+* @template TValue The type of the value returned by the wrapped parser.
+* @template TState The type of the state used by the wrapped parser.
+* @param parser The {@link Parser} to make optional.
+* @returns A {@link Parser} that produces either the result of the wrapped parser
+*          or `undefined` if the wrapped parser fails to match.
+*/
+function optional(parser) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: void 0,
+		parse(context) {
+			const result = parser.parse({
+				...context,
+				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+			});
+			if (result.success) return {
+				success: true,
+				next: {
+					...result.next,
+					state: [result.next.state]
+				},
+				consumed: result.consumed
+			};
+			return result;
+		},
+		complete(state) {
+			if (typeof state === "undefined") return {
+				success: true,
+				value: void 0
+			};
+			return parser.complete(state[0]);
+		},
+		getDocFragments(state, defaultValue) {
+			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], defaultValue);
+		}
+	};
+}
+/**
+* Creates a parser that makes another parser use a default value when it fails
+* to match or consume input. This is similar to {@link optional}, but instead
+* of returning `undefined` when the wrapped parser doesn't match, it returns
+* a specified default value.
+* @template TValue The type of the value returned by the wrapped parser.
+* @template TState The type of the state used by the wrapped parser.
+* @param parser The {@link Parser} to wrap with default behavior.
+* @param defaultValue The default value to return when the wrapped parser
+*                     doesn't match or consume input. Can be a value of type
+*                     {@link TValue} or a function that returns such a value.
+* @returns A {@link Parser} that produces either the result of the wrapped parser
+*          or the default value if the wrapped parser fails to match.
+*/
+function withDefault(parser, defaultValue) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: void 0,
+		parse(context) {
+			const result = parser.parse({
+				...context,
+				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+			});
+			if (result.success) return {
+				success: true,
+				next: {
+					...result.next,
+					state: [result.next.state]
+				},
+				consumed: result.consumed
+			};
+			return result;
+		},
+		complete(state) {
+			if (typeof state === "undefined") return {
+				success: true,
+				value: typeof defaultValue === "function" ? defaultValue() : defaultValue
+			};
+			return parser.complete(state[0]);
+		},
+		getDocFragments(state, upperDefaultValue) {
+			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], upperDefaultValue == null ? typeof defaultValue === "function" ? defaultValue() : defaultValue : upperDefaultValue);
+		}
+	};
+}
+/**
+* Creates a parser that allows multiple occurrences of a given parser.
+* This parser can be used to parse multiple values of the same type,
+* such as multiple command-line arguments or options.
+* @template TValue The type of the value that the parser produces.
+* @template TState The type of the state used by the parser.
+* @param parser The {@link Parser} to apply multiple times.
+* @param options Optional configuration for the parser,
+*                allowing you to specify the minimum and maximum number of
+*                occurrences allowed.
+* @returns A {@link Parser} that produces an array of values
+*          of type {@link TValue} and an array of states
+*          of type {@link TState}.
+*/
+function multiple(parser, options = {}) {
+	const { min = 0, max = Infinity } = options;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "multiple",
+			terms: parser.usage,
+			min
+		}],
+		initialState: [],
+		parse(context) {
+			let added = context.state.length < 1;
+			let result = parser.parse({
+				...context,
+				state: context.state.at(-1) ?? parser.initialState
+			});
+			if (!result.success) if (!added) {
+				result = parser.parse({
+					...context,
+					state: parser.initialState
+				});
+				if (!result.success) return result;
+				added = true;
+			} else return result;
+			return {
+				success: true,
+				next: {
+					...result.next,
+					state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				},
+				consumed: result.consumed
+			};
+		},
+		complete(state) {
+			const result = [];
+			for (const s of state) {
+				const valueResult = parser.complete(s);
+				if (valueResult.success) result.push(valueResult.value);
+				else return {
+					success: false,
+					error: valueResult.error
+				};
+			}
+			if (result.length < min) return {
+				success: false,
+				error: require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.text(result.length.toLocaleString("en"))}.`
+			};
+			else if (result.length > max) return {
+				success: false,
+				error: require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(result.length.toLocaleString("en"))}.`
+			};
+			return {
+				success: true,
+				value: result
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			return parser.getDocFragments(state.at(-1) ?? parser.initialState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+		}
+	};
+}
+function object(labelOrParsers, maybeParsers) {
+	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	const parsers = typeof labelOrParsers === "string" ? maybeParsers : labelOrParsers;
+	const parserPairs = Object.entries(parsers);
+	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: Math.max(...Object.values(parsers).map((p) => p.priority)),
+		usage: parserPairs.flatMap(([_, p]) => p.usage),
+		initialState: Object.fromEntries(Object.entries(parsers).map(([key, parser]) => [key, parser.initialState])),
+		parse(context) {
+			let error = {
+				consumed: 0,
+				error: context.buffer.length > 0 ? require_message.message`Unexpected option or argument: ${context.buffer[0]}.` : require_message.message`Expected an option or argument, but got end of input.`
+			};
+			for (const [field, parser] of parserPairs) {
+				const result = parser.parse({
+					...context,
+					state: context.state[field]
+				});
+				if (result.success && result.consumed.length > 0) return {
+					success: true,
+					next: {
+						...context,
+						buffer: result.next.buffer,
+						optionsTerminated: result.next.optionsTerminated,
+						state: {
+							...context.state,
+							[field]: result.next.state
+						}
+					},
+					consumed: result.consumed
+				};
+				else if (!result.success && error.consumed < result.consumed) error = result;
+			}
+			return {
+				...error,
+				success: false
+			};
+		},
+		complete(state) {
+			const result = {};
+			for (const field in state) {
+				if (!(field in parsers)) continue;
+				const valueResult = parsers[field].complete(state[field]);
+				if (valueResult.success) result[field] = valueResult.value;
+				else return {
+					success: false,
+					error: valueResult.error
+				};
+			}
+			return {
+				success: true,
+				value: result
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			const fragments = parserPairs.flatMap(([field, p]) => p.getDocFragments(state[field], defaultValue?.[field]).fragments);
+			const entries = fragments.filter((d) => d.type === "entry");
+			const sections = [];
+			for (const fragment of fragments) {
+				if (fragment.type !== "section") continue;
+				if (fragment.title == null) entries.push(...fragment.entries);
+				else sections.push(fragment);
+			}
+			const section = {
+				title: label,
+				entries
+			};
+			sections.push(section);
+			return { fragments: sections.map((s) => ({
+				...s,
+				type: "section"
+			})) };
+		}
+	};
+}
+function tuple(labelOrParsers, maybeParsers) {
+	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	const parsers = typeof labelOrParsers === "string" ? maybeParsers : labelOrParsers;
+	return {
+		$valueType: [],
+		$stateType: [],
+		usage: parsers.toSorted((a, b) => b.priority - a.priority).flatMap((p) => p.usage),
+		priority: parsers.length > 0 ? Math.max(...parsers.map((p) => p.priority)) : 0,
+		initialState: parsers.map((parser) => parser.initialState),
+		parse(context) {
+			let currentContext = context;
+			const allConsumed = [];
+			const matchedParsers = /* @__PURE__ */ new Set();
+			while (matchedParsers.size < parsers.length) {
+				let foundMatch = false;
+				let error = {
+					consumed: 0,
+					error: require_message.message`No remaining parsers could match the input.`
+				};
+				const remainingParsers = parsers.map((parser, index) => [parser, index]).filter(([_, index]) => !matchedParsers.has(index)).sort(([parserA], [parserB]) => parserB.priority - parserA.priority);
+				for (const [parser, index] of remainingParsers) {
+					const result = parser.parse({
+						...currentContext,
+						state: currentContext.state[index]
+					});
+					if (result.success && result.consumed.length > 0) {
+						currentContext = {
+							...currentContext,
+							buffer: result.next.buffer,
+							optionsTerminated: result.next.optionsTerminated,
+							state: currentContext.state.map((s, idx) => idx === index ? result.next.state : s)
+						};
+						allConsumed.push(...result.consumed);
+						matchedParsers.add(index);
+						foundMatch = true;
+						break;
+					} else if (!result.success && error.consumed < result.consumed) error = result;
+				}
+				if (!foundMatch) for (const [parser, index] of remainingParsers) {
+					const result = parser.parse({
+						...currentContext,
+						state: currentContext.state[index]
+					});
+					if (result.success && result.consumed.length < 1) {
+						currentContext = {
+							...currentContext,
+							state: currentContext.state.map((s, idx) => idx === index ? result.next.state : s)
+						};
+						matchedParsers.add(index);
+						foundMatch = true;
+						break;
+					} else if (!result.success && result.consumed < 1) {
+						matchedParsers.add(index);
+						foundMatch = true;
+						break;
+					}
+				}
+				if (!foundMatch) return {
+					...error,
+					success: false
+				};
+			}
+			return {
+				success: true,
+				next: currentContext,
+				consumed: allConsumed
+			};
+		},
+		complete(state) {
+			const result = [];
+			for (let i = 0; i < parsers.length; i++) {
+				const valueResult = parsers[i].complete(state[i]);
+				if (valueResult.success) result[i] = valueResult.value;
+				else return {
+					success: false,
+					error: valueResult.error
+				};
+			}
+			return {
+				success: true,
+				value: result
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			const fragments = parsers.flatMap((p, i) => p.getDocFragments(state[i], defaultValue?.[i]).fragments);
+			const entries = fragments.filter((d) => d.type === "entry");
+			const sections = [];
+			for (const fragment of fragments) {
+				if (fragment.type !== "section") continue;
+				if (fragment.title == null) entries.push(...fragment.entries);
+				else sections.push(fragment);
+			}
+			const section = {
+				title: label,
+				entries
+			};
+			sections.push(section);
+			return { fragments: sections.map((s) => ({
+				...s,
+				type: "section"
+			})) };
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			const parsersStr = parsers.length === 1 ? `[1 parser]` : `[${parsers.length} parsers]`;
+			return label ? `tuple(${JSON.stringify(label)}, ${parsersStr})` : `tuple(${parsersStr})`;
+		}
+	};
+}
+function or(...parsers) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: Math.max(...parsers.map((p) => p.priority)),
+		usage: [{
+			type: "exclusive",
+			terms: parsers.map((p) => p.usage)
+		}],
+		initialState: void 0,
+		complete(state) {
+			if (state == null) return {
+				success: false,
+				error: require_message.message`No parser matched.`
+			};
+			const [i, result] = state;
+			if (result.success) return parsers[i].complete(result.next.state);
+			return {
+				success: false,
+				error: result.error
+			};
+		},
+		parse(context) {
+			let error = {
+				consumed: 0,
+				error: context.buffer.length < 1 ? require_message.message`No parser matched.` : require_message.message`Unexpected option or subcommand: ${require_message.optionName(context.buffer[0])}.`
+			};
+			const orderedParsers = parsers.map((p, i) => [p, i]);
+			orderedParsers.sort(([_, a], [__, b]) => context.state?.[0] === a ? -1 : context.state?.[0] === b ? 1 : a - b);
+			for (const [parser, i] of orderedParsers) {
+				const result = parser.parse({
+					...context,
+					state: context.state == null || context.state[0] !== i || !context.state[1].success ? parser.initialState : context.state[1].next.state
+				});
+				if (result.success && result.consumed.length > 0) {
+					if (context.state?.[0] !== i && context.state?.[1].success) return {
+						success: false,
+						consumed: context.buffer.length - result.next.buffer.length,
+						error: require_message.message`${require_message.values(context.state[1].consumed)} and ${require_message.values(result.consumed)} cannot be used together.`
+					};
+					return {
+						success: true,
+						next: {
+							...context,
+							buffer: result.next.buffer,
+							optionsTerminated: result.next.optionsTerminated,
+							state: [i, result]
+						},
+						consumed: result.consumed
+					};
+				} else if (!result.success && error.consumed < result.consumed) error = result;
+			}
+			return {
+				...error,
+				success: false
+			};
+		},
+		getDocFragments(state, _defaultValue) {
+			let description;
+			let fragments;
+			if (state == null) fragments = parsers.flatMap((p) => p.getDocFragments(p.initialState, void 0).fragments);
+			else {
+				const [index, parserResult] = state;
+				const docFragments = parsers[index].getDocFragments(parserResult.success ? parserResult.next.state : parsers[index].initialState, void 0);
+				description = docFragments.description;
+				fragments = docFragments.fragments;
+			}
+			const entries = fragments.filter((f) => f.type === "entry");
+			const sections = [];
+			for (const fragment of fragments) {
+				if (fragment.type !== "section") continue;
+				if (fragment.title == null) entries.push(...fragment.entries);
+				else sections.push(fragment);
+			}
+			return {
+				description,
+				fragments: [...sections.map((s) => ({
+					...s,
+					type: "section"
+				})), {
+					type: "section",
+					entries
+				}]
+			};
+		}
+	};
+}
+function merge(...parsers) {
+	parsers = parsers.toSorted((a, b) => b.priority - a.priority);
+	const initialState = {};
+	for (const parser of parsers) for (const field in parser.initialState) initialState[field] = parser.initialState[field];
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: Math.max(...parsers.map((p) => p.priority)),
+		usage: parsers.flatMap((p) => p.usage),
+		initialState,
+		parse(context) {
+			for (const parser of parsers) {
+				const result = parser.parse(context);
+				if (result.success) return {
+					success: true,
+					next: {
+						...context,
+						buffer: result.next.buffer,
+						optionsTerminated: result.next.optionsTerminated,
+						state: {
+							...context.state,
+							...result.next.state
+						}
+					},
+					consumed: result.consumed
+				};
+				else if (result.consumed < 1) continue;
+				else return result;
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`No parser matched the input.`
+			};
+		},
+		complete(state) {
+			const object$1 = {};
+			for (const parser of parsers) {
+				const result = parser.complete(state);
+				if (!result.success) return result;
+				for (const field in result.value) object$1[field] = result.value[field];
+			}
+			return {
+				success: true,
+				value: object$1
+			};
+		},
+		getDocFragments(state, _defaultValue) {
+			const fragments = parsers.flatMap((p) => p.getDocFragments(state, void 0).fragments);
+			const entries = fragments.filter((f) => f.type === "entry");
+			const sections = [];
+			for (const fragment of fragments) {
+				if (fragment.type !== "section") continue;
+				if (fragment.title == null) entries.push(...fragment.entries);
+				else sections.push(fragment);
+			}
+			return { fragments: [...sections.map((s) => ({
+				...s,
+				type: "section"
+			})), {
+				type: "section",
+				entries
+			}] };
+		}
+	};
+}
+/**
+* Creates a parser that matches a specific subcommand name and then applies
+* an inner parser to the remaining arguments.
+* This is useful for building CLI tools with subcommands like git, npm, etc.
+* @template T The type of the value returned by the inner parser.
+* @template TState The type of the state used by the inner parser.
+* @param name The subcommand name to match (e.g., `"show"`, `"edit"`).
+* @param parser The {@link Parser} to apply after the command is matched.
+* @param options Optional configuration for the command parser, such as
+*                a description for documentation.
+* @returns A {@link Parser} that matches the command name and delegates
+*          to the inner parser for the remaining arguments.
+*/
+function command(name, parser, options = {}) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 15,
+		usage: [{
+			type: "command",
+			name
+		}, ...parser.usage],
+		initialState: void 0,
+		parse(context) {
+			if (context.state === void 0) {
+				if (context.buffer.length < 1 || context.buffer[0] !== name) return {
+					success: false,
+					consumed: 0,
+					error: require_message.message`Expected command ${require_message.optionName(name)}, but got ${context.buffer.length > 0 ? context.buffer[0] : "end of input"}.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: ["matched", name]
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+			} else if (context.state[0] === "matched") {
+				const result = parser.parse({
+					...context,
+					state: parser.initialState
+				});
+				if (result.success) return {
+					success: true,
+					next: {
+						...result.next,
+						state: ["parsing", result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return result;
+			} else if (context.state[0] === "parsing") {
+				const result = parser.parse({
+					...context,
+					state: context.state[1]
+				});
+				if (result.success) return {
+					success: true,
+					next: {
+						...result.next,
+						state: ["parsing", result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return result;
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: require_message.message`Invalid command state.`
+			};
+		},
+		complete(state) {
+			if (typeof state === "undefined") return {
+				success: false,
+				error: require_message.message`Command ${require_message.optionName(name)} was not matched.`
+			};
+			else if (state[0] === "matched") return parser.complete(parser.initialState);
+			else if (state[0] === "parsing") return parser.complete(state[1]);
+			return {
+				success: false,
+				error: require_message.message`Invalid command state during completion.`
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			if (typeof state === "undefined") return {
+				description: options.description,
+				fragments: [{
+					type: "entry",
+					term: {
+						type: "command",
+						name
+					},
+					description: options.description
+				}]
+			};
+			const innerFragments = parser.getDocFragments(state[0] === "parsing" ? state[1] : parser.initialState, defaultValue);
+			return {
+				...innerFragments,
+				description: innerFragments.description ?? options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `command(${JSON.stringify(name)})`;
+		}
+	};
+}
+/**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @returns A {@link Result} object indicating whether the parsing was
+*          successful or not.  If successful, it contains the parsed value of
+*          type `T`.  If not, it contains an error message describing the
+*          failure.
+*/
+function parse(parser, args) {
+	let context = {
+		buffer: args,
+		optionsTerminated: false,
+		state: parser.initialState
+	};
+	do {
+		const result = parser.parse(context);
+		if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+		context = result.next;
+	} while (context.buffer.length > 0);
+	const endResult = parser.complete(context.state);
+	return endResult.success ? {
+		success: true,
+		value: endResult.value
+	} : {
+		success: false,
+		error: endResult.error
+	};
+}
+/**
+* Generates a documentation page for a parser based on its current state after
+* attempting to parse the provided arguments. This function is useful for
+* creating help documentation that reflects the current parsing context.
+*
+* The function works by:
+* 1. Attempting to parse the provided arguments to determine the current state
+* 2. Generating documentation fragments from the parser's current state
+* 3. Organizing fragments into entries and sections
+* 4. Resolving command usage terms based on parsed arguments
+*
+* @param parser The parser to generate documentation for
+* @param args Optional array of command-line arguments that have been parsed
+*             so far. Defaults to an empty array. This is used to determine
+*             the current parsing context and generate contextual documentation.
+* @returns A {@link DocPage} containing usage information, sections, and
+*          optional description, or `undefined` if no documentation can be
+*          generated.
+*
+* @example
+* ```typescript
+* const parser = object({
+*   verbose: option("-v", "--verbose"),
+*   port: option("-p", "--port", integer())
+* });
+*
+* // Get documentation for the root parser
+* const rootDoc = getDocPage(parser);
+*
+* // Get documentation after parsing some arguments
+* const contextDoc = getDocPage(parser, ["-v"]);
+* ```
+*/
+function getDocPage(parser, args = []) {
+	let context = {
+		buffer: args,
+		optionsTerminated: false,
+		state: parser.initialState
+	};
+	do {
+		const result = parser.parse(context);
+		if (!result.success) break;
+		context = result.next;
+	} while (context.buffer.length > 0);
+	const { description, fragments } = parser.getDocFragments(context.state, void 0);
+	const entries = fragments.filter((f) => f.type === "entry");
+	const sections = [];
+	for (const fragment of fragments) {
+		if (fragment.type !== "section") continue;
+		if (fragment.title == null) entries.push(...fragment.entries);
+		else sections.push(fragment);
+	}
+	if (entries.length > 0) sections.push({ entries });
+	const usage = [...require_usage.normalizeUsage(parser.usage)];
+	let i = 0;
+	for (const arg of args) {
+		const term = usage[i];
+		if (usage.length > i && term.type === "exclusive") for (const termGroup of term.terms) {
+			const firstTerm = termGroup[0];
+			if (firstTerm?.type !== "command" || firstTerm.name !== arg) continue;
+			usage.splice(i, 1, ...termGroup);
+			break;
+		}
+		i++;
+	}
+	return description == null ? {
+		usage,
+		sections
+	} : {
+		usage,
+		sections,
+		description
+	};
+}
+
+//#endregion
+exports.argument = argument;
+exports.command = command;
+exports.constant = constant;
+exports.getDocPage = getDocPage;
+exports.merge = merge;
+exports.multiple = multiple;
+exports.object = object;
+exports.option = option;
+exports.optional = optional;
+exports.or = or;
+exports.parse = parse;
+exports.tuple = tuple;
+exports.withDefault = withDefault;