@optique/core 0.3.0-dev.39 → 0.3.0-dev.41

package/dist/facade.cjs

@@ -38,22 +38,48 @@ function run(parser, programName, args, options = {}) {
 	let { colors, maxWidth, help = "none", onHelp = () => {}, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log } = options;
+	const contextualHelpParser = require_parser.object({
+		help: require_parser.constant(true),
+		commands: require_parser.multiple(require_parser.argument(require_valueparser.string({ metavar: "COMMAND" }))),
+		__help: require_parser.flag("--help")
+	});
 	const helpCommand = require_parser.command("help", require_parser.multiple(require_parser.argument(require_valueparser.string({ metavar: "COMMAND" }))), { description: require_message.message`Show help information.` });
 	const helpOption = require_parser.option("--help", { description: require_message.message`Show help information.` });
-	const augmentedParser = help === "none" ? require_parser.object({
+	const augmentedParser = help === "none" ? parser : help === "command" ? require_parser.longestMatch(require_parser.object({
+		help: require_parser.constant(true),
+		commands: helpCommand
+	}), require_parser.object({
 		help: require_parser.constant(false),
 		result: parser
-	}) : require_parser.or(require_parser.object({
+	})) : help === "option" ? require_parser.longestMatch(require_parser.object({
+		help: require_parser.constant(false),
+		result: parser
+	}), contextualHelpParser, require_parser.merge(require_parser.object({
+		help: require_parser.constant(true),
+		commands: require_parser.constant([])
+	}), helpOption)) : require_parser.longestMatch(require_parser.object({
 		help: require_parser.constant(false),
 		result: parser
 	}), require_parser.object({
 		help: require_parser.constant(true),
-		command: help === "both" ? require_parser.or(helpCommand, helpOption) : help === "command" ? helpCommand : helpOption
-	}));
+		commands: helpCommand
+	}), contextualHelpParser, require_parser.merge(require_parser.object({
+		help: require_parser.constant(true),
+		commands: require_parser.constant([])
+	}), helpOption));
 	const result = require_parser.parse(augmentedParser, args);
 	if (result.success) {
-		if (!result.value.help) return result.value.result;
-		const doc = require_parser.getDocPage(typeof result.value.command === "boolean" || result.value.command.length < 1 ? augmentedParser : parser, typeof result.value.command === "boolean" ? [] : result.value.command);
+		const value = result.value;
+		if (help === "none") return value;
+		if (typeof value === "object" && value != null && "help" in value) {
+			const helpValue$1 = value;
+			if (!helpValue$1.help) return helpValue$1.result;
+		} else return value;
+		let commandContext = [];
+		const helpValue = value;
+		if (Array.isArray(helpValue.commands)) commandContext = helpValue.commands;
+		else if (typeof helpValue.commands === "object" && helpValue.commands != null && "length" in helpValue.commands) commandContext = helpValue.commands;
+		const doc = require_parser.getDocPage(commandContext.length < 1 ? augmentedParser : parser, commandContext);
 		if (doc != null) stdout(require_doc.formatDocPage(programName, doc, {
 			colors,
 			maxWidth

package/dist/facade.js

@@ -2,7 +2,7 @@ import { formatMessage, message } from "./message.js";
 import { formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { string } from "./valueparser.js";
-import { argument, command, constant, getDocPage, multiple, object, option, or, parse } from "./parser.js";
+import { argument, command, constant, flag, getDocPage, longestMatch, merge, multiple, object, option, parse } from "./parser.js";
 
 //#region src/facade.ts
 /**
@@ -38,22 +38,48 @@ function run(parser, programName, args, options = {}) {
 	let { colors, maxWidth, help = "none", onHelp = () => {}, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log } = options;
+	const contextualHelpParser = object({
+		help: constant(true),
+		commands: multiple(argument(string({ metavar: "COMMAND" }))),
+		__help: flag("--help")
+	});
 	const helpCommand = command("help", multiple(argument(string({ metavar: "COMMAND" }))), { description: message`Show help information.` });
 	const helpOption = option("--help", { description: message`Show help information.` });
-	const augmentedParser = help === "none" ? object({
+	const augmentedParser = help === "none" ? parser : help === "command" ? longestMatch(object({
+		help: constant(true),
+		commands: helpCommand
+	}), object({
 		help: constant(false),
 		result: parser
-	}) : or(object({
+	})) : help === "option" ? longestMatch(object({
+		help: constant(false),
+		result: parser
+	}), contextualHelpParser, merge(object({
+		help: constant(true),
+		commands: constant([])
+	}), helpOption)) : longestMatch(object({
 		help: constant(false),
 		result: parser
 	}), object({
 		help: constant(true),
-		command: help === "both" ? or(helpCommand, helpOption) : help === "command" ? helpCommand : helpOption
-	}));
+		commands: helpCommand
+	}), contextualHelpParser, merge(object({
+		help: constant(true),
+		commands: constant([])
+	}), helpOption));
 	const result = parse(augmentedParser, args);
 	if (result.success) {
-		if (!result.value.help) return result.value.result;
-		const doc = getDocPage(typeof result.value.command === "boolean" || result.value.command.length < 1 ? augmentedParser : parser, typeof result.value.command === "boolean" ? [] : result.value.command);
+		const value = result.value;
+		if (help === "none") return value;
+		if (typeof value === "object" && value != null && "help" in value) {
+			const helpValue$1 = value;
+			if (!helpValue$1.help) return helpValue$1.result;
+		} else return value;
+		let commandContext = [];
+		const helpValue = value;
+		if (Array.isArray(helpValue.commands)) commandContext = helpValue.commands;
+		else if (typeof helpValue.commands === "object" && helpValue.commands != null && "length" in helpValue.commands) commandContext = helpValue.commands;
+		const doc = getDocPage(commandContext.length < 1 ? augmentedParser : parser, commandContext);
 		if (doc != null) stdout(formatDocPage(programName, doc, {
 			colors,
 			maxWidth

package/dist/index.cjs

@@ -21,6 +21,7 @@ exports.getDocPage = require_parser.getDocPage;
 exports.integer = require_valueparser.integer;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.locale = require_valueparser.locale;
+exports.longestMatch = require_parser.longestMatch;
 exports.map = require_parser.map;
 exports.merge = require_parser.merge;
 exports.message = require_message.message;

package/dist/index.d.cts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
-import { ArgumentOptions, CommandOptions, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.d.ts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { ArgumentOptions, CommandOptions, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.js

@@ -2,7 +2,7 @@ import { formatMessage, message, metavar, optionName, optionNames, text, value,
 import { formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { RunError, argument, choice, command, concat, constant, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/parser.cjs

@@ -514,7 +514,11 @@ function optional(parser) {
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, defaultValue) {
-			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], defaultValue);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			return parser.getDocFragments(innerState, defaultValue);
 		}
 	};
 }
@@ -566,7 +570,11 @@ function withDefault(parser, defaultValue) {
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, upperDefaultValue) {
-			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			return parser.getDocFragments(innerState, upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
 		}
 	};
 }
@@ -697,7 +705,11 @@ function multiple(parser, options = {}) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			return parser.getDocFragments(state.at(-1) ?? parser.initialState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+				kind: "available",
+				state: state.state.at(-1)
+			} : { kind: "unavailable" };
+			return parser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}
 	};
 }
@@ -788,7 +800,13 @@ function object(labelOrParsers, maybeParsers) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			const fragments = parserPairs.flatMap(([field, p]) => p.getDocFragments(state[field], defaultValue?.[field]).fragments);
+			const fragments = parserPairs.flatMap(([field, p]) => {
+				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[field]
+				};
+				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -892,7 +910,13 @@ function tuple(labelOrParsers, maybeParsers) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			const fragments = parsers.flatMap((p, i) => p.getDocFragments(state[i], defaultValue?.[i]).fragments);
+			const fragments = parsers.flatMap((p, i) => {
+				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[i]
+				};
+				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -976,10 +1000,14 @@ function or(...parsers) {
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let fragments;
-			if (state == null) fragments = parsers.flatMap((p) => p.getDocFragments(p.initialState, void 0).fragments);
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
 			else {
-				const [index, parserResult] = state;
-				const docFragments = parsers[index].getDocFragments(parserResult.success ? parserResult.next.state : parsers[index].initialState, void 0);
+				const [index, parserResult] = state.state;
+				const innerState = parserResult.success ? {
+					kind: "available",
+					state: parserResult.next.state
+				} : { kind: "unavailable" };
+				const docFragments = parsers[index].getDocFragments(innerState, void 0);
 				description = docFragments.description;
 				fragments = docFragments.fragments;
 			}
@@ -1003,6 +1031,86 @@ function or(...parsers) {
 		}
 	};
 }
+function longestMatch(...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 bestMatch = null;
+			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])}.`
+			};
+			for (let i = 0; i < parsers.length; i++) {
+				const parser = parsers[i];
+				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) {
+					const consumed = context.buffer.length - result.next.buffer.length;
+					if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+						index: i,
+						result,
+						consumed
+					};
+				} else if (error.consumed < result.consumed) error = result;
+			}
+			if (bestMatch && bestMatch.result.success) return {
+				success: true,
+				next: {
+					...context,
+					buffer: bestMatch.result.next.buffer,
+					optionsTerminated: bestMatch.result.next.optionsTerminated,
+					state: [bestMatch.index, bestMatch.result]
+				},
+				consumed: bestMatch.result.consumed
+			};
+			return {
+				...error,
+				success: false
+			};
+		},
+		getDocFragments(state, _defaultValue) {
+			let description;
+			let fragments;
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+			else {
+				const [i, result] = state.state;
+				if (result.success) {
+					const docResult = parsers[i].getDocFragments({
+						kind: "available",
+						state: result.next.state
+					});
+					description = docResult.description;
+					fragments = docResult.fragments;
+				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+			}
+			return {
+				description,
+				fragments
+			};
+		}
+	};
+}
 function merge(...parsers) {
 	parsers = parsers.toSorted((a, b) => b.priority - a.priority);
 	const initialState = {};
@@ -1082,7 +1190,13 @@ function merge(...parsers) {
 			};
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p) => p.getDocFragments(state, void 0).fragments);
+			const fragments = parsers.flatMap((p) => {
+				const parserState = p.initialState === void 0 ? { kind: "unavailable" } : state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state
+				};
+				return p.getDocFragments(parserState, void 0).fragments;
+			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -1183,7 +1297,13 @@ function concat(...parsers) {
 			};
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p, index) => p.getDocFragments(state[index], void 0).fragments);
+			const fragments = parsers.flatMap((p, index) => {
+				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[index]
+				};
+				return p.getDocFragments(indexState, void 0).fragments;
+			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -1290,7 +1410,7 @@ function command(name, parser, options = {}) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			if (typeof state === "undefined") return {
+			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,
 				fragments: [{
 					type: "entry",
@@ -1301,7 +1421,11 @@ function command(name, parser, options = {}) {
 					description: options.description
 				}]
 			};
-			const innerFragments = parser.getDocFragments(state[0] === "parsing" ? state[1] : parser.initialState, defaultValue);
+			const innerState = state.state[0] === "parsing" ? {
+				kind: "available",
+				state: state.state[1]
+			} : { kind: "unavailable" };
+			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {
 				...innerFragments,
 				description: innerFragments.description ?? options.description
@@ -1398,7 +1522,10 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
-	const { description, fragments } = parser.getDocFragments(context.state, void 0);
+	const { description, fragments } = parser.getDocFragments({
+		kind: "available",
+		state: context.state
+	}, void 0);
 	const entries = fragments.filter((f) => f.type === "entry");
 	const sections = [];
 	for (const fragment of fragments) {
@@ -1436,6 +1563,7 @@ exports.concat = concat;
 exports.constant = constant;
 exports.flag = flag;
 exports.getDocPage = getDocPage;
+exports.longestMatch = longestMatch;
 exports.map = map;
 exports.merge = merge;
 exports.multiple = multiple;

package/dist/parser.d.cts

@@ -5,6 +5,19 @@ import { ValueParser, ValueParserResult } from "./valueparser.cjs";
 
 //#region src/parser.d.ts
 
+/**
+ * Represents the state passed to getDocFragments.
+ * Can be either the actual parser state or an explicit indicator
+ * that no state is available.
+ * @template TState The type of the actual state when available.
+ * @since 0.3.0
+ */
+type DocState<TState> = {
+  readonly kind: "available";
+  readonly state: TState;
+} | {
+  readonly kind: "unavailable";
+};
 /**
  * Parser interface for command-line argument parsing.
  * @template TValue The type of the value returned by the parser.
@@ -65,15 +78,14 @@ interface Parser<TValue, TState> {
   /**
    * Generates a documentation fragment for this parser, which can be used
    * to describe the parser's usage, description, and default value.
-   * @param state The current state of the parser, which may contain
-   *              accumulated data or context needed to produce
-   *              the documentation.
+   * @param state The current state of the parser, wrapped in a DocState
+   *              to indicate whether the actual state is available or not.
    * @param defaultValue An optional default value that can be used
    *                     to provide a default value in the documentation.
    * @returns {@link DocFragments} object containing documentation
    *          fragments for this parser.
    */
-  getDocFragments(state: TState, defaultValue?: TValue): DocFragments;
+  getDocFragments(state: DocState<TState>, defaultValue?: TValue): DocFragments;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.
@@ -636,6 +648,84 @@ declare function or<TA, TB, TC, TD, TE, TF, TG, TH, TI, TStateA, TStateB, TState
  *         in order, returning the result of the first successful parser.
  */
 declare function or<TA, TB, TC, TD, TE, TF, TG, TH, TI, TJ, TStateA, TStateB, TStateC, TStateD, TStateE, TStateF, TStateG, TStateH, TStateI, TStateJ>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>, e: Parser<TE, TStateE>, f: Parser<TF, TStateF>, g: Parser<TG, TStateG>, h: Parser<TH, TStateH>, i: Parser<TI, TStateI>, j: Parser<TJ, TStateJ>): Parser<TA | TB | TC | TD | TE | TF | TG | TH | TI | TJ, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>] | [4, ParserResult<TStateE>] | [5, ParserResult<TStateF>] | [6, ParserResult<TStateG>] | [7, ParserResult<TStateH>] | [8, ParserResult<TStateI>] | [9, ParserResult<TStateJ>]>;
+/**
+ * Creates a parser that combines two mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try both parsers and return the result
+ * of the parser that consumed more input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using both parsers
+ *          and returns the result of the parser that consumed more tokens.
+ */
+declare function longestMatch<TA, TB, TStateA, TStateB>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>): Parser<TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
+/**
+ * Creates a parser that combines three mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>): Parser<TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
+/**
+ * Creates a parser that combines four mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TD, TStateA, TStateB, TStateC, TStateD>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>): Parser<TA | TB | TC | TD, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>]>;
+/**
+ * Creates a parser that combines five mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TE The type of the value returned by the fifth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @template TStateE The type of the state used by the fifth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @param e The fifth {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TD, TE, TStateA, TStateB, TStateC, TStateD, TStateE>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>, e: Parser<TE, TStateE>): Parser<TA | TB | TC | TD | TE, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>] | [4, ParserResult<TStateE>]>;
 /**
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
@@ -924,4 +1014,4 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.d.ts

@@ -5,6 +5,19 @@ import { ValueParser, ValueParserResult } from "./valueparser.js";
 
 //#region src/parser.d.ts
 
+/**
+ * Represents the state passed to getDocFragments.
+ * Can be either the actual parser state or an explicit indicator
+ * that no state is available.
+ * @template TState The type of the actual state when available.
+ * @since 0.3.0
+ */
+type DocState<TState> = {
+  readonly kind: "available";
+  readonly state: TState;
+} | {
+  readonly kind: "unavailable";
+};
 /**
  * Parser interface for command-line argument parsing.
  * @template TValue The type of the value returned by the parser.
@@ -65,15 +78,14 @@ interface Parser<TValue, TState> {
   /**
    * Generates a documentation fragment for this parser, which can be used
    * to describe the parser's usage, description, and default value.
-   * @param state The current state of the parser, which may contain
-   *              accumulated data or context needed to produce
-   *              the documentation.
+   * @param state The current state of the parser, wrapped in a DocState
+   *              to indicate whether the actual state is available or not.
    * @param defaultValue An optional default value that can be used
    *                     to provide a default value in the documentation.
    * @returns {@link DocFragments} object containing documentation
    *          fragments for this parser.
    */
-  getDocFragments(state: TState, defaultValue?: TValue): DocFragments;
+  getDocFragments(state: DocState<TState>, defaultValue?: TValue): DocFragments;
 }
 /**
  * The context of the parser, which includes the input buffer and the state.
@@ -636,6 +648,84 @@ declare function or<TA, TB, TC, TD, TE, TF, TG, TH, TI, TStateA, TStateB, TState
  *         in order, returning the result of the first successful parser.
  */
 declare function or<TA, TB, TC, TD, TE, TF, TG, TH, TI, TJ, TStateA, TStateB, TStateC, TStateD, TStateE, TStateF, TStateG, TStateH, TStateI, TStateJ>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>, e: Parser<TE, TStateE>, f: Parser<TF, TStateF>, g: Parser<TG, TStateG>, h: Parser<TH, TStateH>, i: Parser<TI, TStateI>, j: Parser<TJ, TStateJ>): Parser<TA | TB | TC | TD | TE | TF | TG | TH | TI | TJ, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>] | [4, ParserResult<TStateE>] | [5, ParserResult<TStateF>] | [6, ParserResult<TStateG>] | [7, ParserResult<TStateH>] | [8, ParserResult<TStateI>] | [9, ParserResult<TStateJ>]>;
+/**
+ * Creates a parser that combines two mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try both parsers and return the result
+ * of the parser that consumed more input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using both parsers
+ *          and returns the result of the parser that consumed more tokens.
+ */
+declare function longestMatch<TA, TB, TStateA, TStateB>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>): Parser<TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
+/**
+ * Creates a parser that combines three mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>): Parser<TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
+/**
+ * Creates a parser that combines four mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TD, TStateA, TStateB, TStateC, TStateD>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>): Parser<TA | TB | TC | TD, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>]>;
+/**
+ * Creates a parser that combines five mutually exclusive parsers into one,
+ * selecting the parser that consumes the most tokens.
+ * The resulting parser will try all parsers and return the result
+ * of the parser that consumed the most input tokens.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TE The type of the value returned by the fifth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @template TStateE The type of the state used by the fifth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @param e The fifth {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using all parsers
+ *          and returns the result of the parser that consumed the most tokens.
+ */
+declare function longestMatch<TA, TB, TC, TD, TE, TStateA, TStateB, TStateC, TStateD, TStateE>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>, e: Parser<TE, TStateE>): Parser<TA | TB | TC | TD | TE, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>] | [4, ParserResult<TStateE>]>;
 /**
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
@@ -924,4 +1014,4 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.js

@@ -514,7 +514,11 @@ function optional(parser) {
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, defaultValue) {
-			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], defaultValue);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			return parser.getDocFragments(innerState, defaultValue);
 		}
 	};
 }
@@ -566,7 +570,11 @@ function withDefault(parser, defaultValue) {
 			return parser.complete(state[0]);
 		},
 		getDocFragments(state, upperDefaultValue) {
-			return parser.getDocFragments(typeof state === "undefined" ? parser.initialState : state[0], upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			return parser.getDocFragments(innerState, upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
 		}
 	};
 }
@@ -697,7 +705,11 @@ function multiple(parser, options = {}) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			return parser.getDocFragments(state.at(-1) ?? parser.initialState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+				kind: "available",
+				state: state.state.at(-1)
+			} : { kind: "unavailable" };
+			return parser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
 		}
 	};
 }
@@ -788,7 +800,13 @@ function object(labelOrParsers, maybeParsers) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			const fragments = parserPairs.flatMap(([field, p]) => p.getDocFragments(state[field], defaultValue?.[field]).fragments);
+			const fragments = parserPairs.flatMap(([field, p]) => {
+				const fieldState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[field]
+				};
+				return p.getDocFragments(fieldState, defaultValue?.[field]).fragments;
+			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -892,7 +910,13 @@ function tuple(labelOrParsers, maybeParsers) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			const fragments = parsers.flatMap((p, i) => p.getDocFragments(state[i], defaultValue?.[i]).fragments);
+			const fragments = parsers.flatMap((p, i) => {
+				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[i]
+				};
+				return p.getDocFragments(indexState, defaultValue?.[i]).fragments;
+			});
 			const entries = fragments.filter((d) => d.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -976,10 +1000,14 @@ function or(...parsers) {
 		getDocFragments(state, _defaultValue) {
 			let description;
 			let fragments;
-			if (state == null) fragments = parsers.flatMap((p) => p.getDocFragments(p.initialState, void 0).fragments);
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }, void 0).fragments);
 			else {
-				const [index, parserResult] = state;
-				const docFragments = parsers[index].getDocFragments(parserResult.success ? parserResult.next.state : parsers[index].initialState, void 0);
+				const [index, parserResult] = state.state;
+				const innerState = parserResult.success ? {
+					kind: "available",
+					state: parserResult.next.state
+				} : { kind: "unavailable" };
+				const docFragments = parsers[index].getDocFragments(innerState, void 0);
 				description = docFragments.description;
 				fragments = docFragments.fragments;
 			}
@@ -1003,6 +1031,86 @@ function or(...parsers) {
 		}
 	};
 }
+function longestMatch(...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: 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 bestMatch = null;
+			let error = {
+				consumed: 0,
+				error: context.buffer.length < 1 ? message`No parser matched.` : message`Unexpected option or subcommand: ${optionName(context.buffer[0])}.`
+			};
+			for (let i = 0; i < parsers.length; i++) {
+				const parser = parsers[i];
+				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) {
+					const consumed = context.buffer.length - result.next.buffer.length;
+					if (bestMatch === null || consumed > bestMatch.consumed) bestMatch = {
+						index: i,
+						result,
+						consumed
+					};
+				} else if (error.consumed < result.consumed) error = result;
+			}
+			if (bestMatch && bestMatch.result.success) return {
+				success: true,
+				next: {
+					...context,
+					buffer: bestMatch.result.next.buffer,
+					optionsTerminated: bestMatch.result.next.optionsTerminated,
+					state: [bestMatch.index, bestMatch.result]
+				},
+				consumed: bestMatch.result.consumed
+			};
+			return {
+				...error,
+				success: false
+			};
+		},
+		getDocFragments(state, _defaultValue) {
+			let description;
+			let fragments;
+			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+			else {
+				const [i, result] = state.state;
+				if (result.success) {
+					const docResult = parsers[i].getDocFragments({
+						kind: "available",
+						state: result.next.state
+					});
+					description = docResult.description;
+					fragments = docResult.fragments;
+				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
+			}
+			return {
+				description,
+				fragments
+			};
+		}
+	};
+}
 function merge(...parsers) {
 	parsers = parsers.toSorted((a, b) => b.priority - a.priority);
 	const initialState = {};
@@ -1082,7 +1190,13 @@ function merge(...parsers) {
 			};
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p) => p.getDocFragments(state, void 0).fragments);
+			const fragments = parsers.flatMap((p) => {
+				const parserState = p.initialState === void 0 ? { kind: "unavailable" } : state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state
+				};
+				return p.getDocFragments(parserState, void 0).fragments;
+			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -1183,7 +1297,13 @@ function concat(...parsers) {
 			};
 		},
 		getDocFragments(state, _defaultValue) {
-			const fragments = parsers.flatMap((p, index) => p.getDocFragments(state[index], void 0).fragments);
+			const fragments = parsers.flatMap((p, index) => {
+				const indexState = state.kind === "unavailable" ? { kind: "unavailable" } : {
+					kind: "available",
+					state: state.state[index]
+				};
+				return p.getDocFragments(indexState, void 0).fragments;
+			});
 			const entries = fragments.filter((f) => f.type === "entry");
 			const sections = [];
 			for (const fragment of fragments) {
@@ -1290,7 +1410,7 @@ function command(name, parser, options = {}) {
 			};
 		},
 		getDocFragments(state, defaultValue) {
-			if (typeof state === "undefined") return {
+			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,
 				fragments: [{
 					type: "entry",
@@ -1301,7 +1421,11 @@ function command(name, parser, options = {}) {
 					description: options.description
 				}]
 			};
-			const innerFragments = parser.getDocFragments(state[0] === "parsing" ? state[1] : parser.initialState, defaultValue);
+			const innerState = state.state[0] === "parsing" ? {
+				kind: "available",
+				state: state.state[1]
+			} : { kind: "unavailable" };
+			const innerFragments = parser.getDocFragments(innerState, defaultValue);
 			return {
 				...innerFragments,
 				description: innerFragments.description ?? options.description
@@ -1398,7 +1522,10 @@ function getDocPage(parser, args = []) {
 		if (!result.success) break;
 		context = result.next;
 	} while (context.buffer.length > 0);
-	const { description, fragments } = parser.getDocFragments(context.state, void 0);
+	const { description, fragments } = parser.getDocFragments({
+		kind: "available",
+		state: context.state
+	}, void 0);
 	const entries = fragments.filter((f) => f.type === "entry");
 	const sections = [];
 	for (const fragment of fragments) {
@@ -1430,4 +1557,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { argument, command, concat, constant, flag, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.3.0-dev.39+80d894ad",
+  "version": "0.3.0-dev.41+76c1e568",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",