@optique/core 0.7.0-dev.150 → 0.7.0-dev.153

package/dist/constructs.cjs

@@ -4,6 +4,65 @@ const require_suggestion = require('./suggestion.cjs');
 
 //#region src/constructs.ts
 /**
+* Extracts required (non-optional) usage terms from a usage array.
+* @param usage The usage to extract required terms from
+* @returns Usage containing only required (non-optional) terms
+*/
+function extractRequiredUsage(usage) {
+	const required = [];
+	for (const term of usage) if (term.type === "optional") continue;
+	else if (term.type === "exclusive") {
+		const requiredBranches = term.terms.map((branch) => extractRequiredUsage(branch)).filter((branch) => branch.length > 0);
+		if (requiredBranches.length > 0) required.push({
+			type: "exclusive",
+			terms: requiredBranches
+		});
+	} else if (term.type === "multiple") {
+		if (term.min > 0) {
+			const requiredTerms = extractRequiredUsage(term.terms);
+			if (requiredTerms.length > 0) required.push({
+				type: "multiple",
+				terms: requiredTerms,
+				min: term.min
+			});
+		}
+	} else required.push(term);
+	return required;
+}
+/**
+* Analyzes parsers to determine what types of inputs are expected.
+* @param parsers The parsers being combined
+* @returns Context about what types of inputs are expected
+*/
+function analyzeNoMatchContext(parsers) {
+	const combinedUsage = [{
+		type: "exclusive",
+		terms: parsers.map((p) => p.usage)
+	}];
+	const requiredUsage = extractRequiredUsage(combinedUsage);
+	return {
+		hasOptions: require_usage.extractOptionNames(requiredUsage).size > 0,
+		hasCommands: require_usage.extractCommandNames(requiredUsage).size > 0,
+		hasArguments: require_usage.extractArgumentMetavars(requiredUsage).size > 0
+	};
+}
+/**
+* Generates a contextual error message based on what types of inputs
+* the parsers expect (options, commands, or arguments).
+* @param context Context about what types of inputs are expected
+* @returns An appropriate error message
+*/
+function generateNoMatchError(context) {
+	const { hasOptions, hasCommands, hasArguments } = context;
+	if (hasArguments && !hasOptions && !hasCommands) return require_message.message`Missing required argument.`;
+	else if (hasCommands && !hasOptions && !hasArguments) return require_message.message`No matching command found.`;
+	else if (hasOptions && !hasCommands && !hasArguments) return require_message.message`No matching option found.`;
+	else if (hasCommands && hasOptions && !hasArguments) return require_message.message`No matching option or command found.`;
+	else if (hasArguments && hasOptions && !hasCommands) return require_message.message`No matching option or argument found.`;
+	else if (hasArguments && hasCommands && !hasOptions) return require_message.message`No matching command or argument found.`;
+	else return require_message.message`No matching option, command, or argument found.`;
+}
+/**
 * @since 0.5.0
 */
 function or(...args) {
@@ -16,6 +75,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	const noMatchContext = analyzeNoMatchContext(parsers);
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -26,10 +86,14 @@ function or(...args) {
 		}],
 		initialState: void 0,
 		complete(state) {
-			if (state == null) return {
-				success: false,
-				error: options?.errors?.noMatch ?? require_message.message`No matching option or command found.`
-			};
+			if (state == null) {
+				const customNoMatch = options?.errors?.noMatch;
+				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				return {
+					success: false,
+					error
+				};
+			}
 			const [i, result] = state;
 			if (result.success) return parsers[i].complete(result.next.state);
 			return {
@@ -40,7 +104,10 @@ function or(...args) {
 		parse(context) {
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? require_message.message`No matching option or command found.` : (() => {
+				error: context.buffer.length < 1 ? (() => {
+					const customNoMatch = options?.errors?.noMatch;
+					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				})() : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
 					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
@@ -151,6 +218,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	const noMatchContext = analyzeNoMatchContext(parsers);
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -161,10 +229,14 @@ function longestMatch(...args) {
 		}],
 		initialState: void 0,
 		complete(state) {
-			if (state == null) return {
-				success: false,
-				error: options?.errors?.noMatch ?? require_message.message`No matching option or command found.`
-			};
+			if (state == null) {
+				const customNoMatch = options?.errors?.noMatch;
+				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				return {
+					success: false,
+					error
+				};
+			}
 			const [i, result] = state;
 			if (result.success) return parsers[i].complete(result.next.state);
 			return {
@@ -176,7 +248,10 @@ function longestMatch(...args) {
 			let bestMatch = null;
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? require_message.message`No matching option or command found.` : (() => {
+				error: context.buffer.length < 1 ? (() => {
+					const customNoMatch = options?.errors?.noMatch;
+					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				})() : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = require_message.message`Unexpected option or subcommand: ${require_message.optionName(token)}.`;
 					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
@@ -242,6 +317,7 @@ function longestMatch(...args) {
 		},
 		getDocFragments(state, _defaultValue) {
 			let description;
+			let footer;
 			let fragments;
 			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			else {
@@ -252,12 +328,14 @@ function longestMatch(...args) {
 						state: result.next.state
 					});
 					description = docResult.description;
+					footer = docResult.footer;
 					fragments = docResult.fragments;
 				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			}
 			return {
 				description,
-				fragments
+				fragments,
+				footer
 			};
 		}
 	};
@@ -275,6 +353,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	}
 	const parserPairs = Object.entries(parsers);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const noMatchContext = analyzeNoMatchContext(Object.values(parsers));
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -305,7 +384,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					if (customMessage) return typeof customMessage === "function" ? customMessage(token) : customMessage;
 					const baseError = require_message.message`Unexpected option or argument: ${token}.`;
 					return require_suggestion.createErrorWithSuggestions(baseError, token, context.usage, "both", options.errors?.suggestions);
-				})() : options.errors?.endOfInput ?? require_message.message`Expected an option or argument, but got end of input.`
+				})() : (() => {
+					const customEndOfInput = options.errors?.endOfInput;
+					return customEndOfInput ? typeof customEndOfInput === "function" ? customEndOfInput(noMatchContext) : customEndOfInput : generateNoMatchError(noMatchContext);
+				})()
 			};
 			let currentContext = context;
 			let anySuccess = false;

package/dist/constructs.d.cts

@@ -13,6 +13,25 @@ interface OrOptions {
    */
   errors?: OrErrorOptions;
 }
+/**
+ * Context information about what types of inputs are expected,
+ * used for generating contextual error messages.
+ * @since 0.9.0
+ */
+interface NoMatchContext {
+  /**
+   * Whether any of the parsers expect options.
+   */
+  readonly hasOptions: boolean;
+  /**
+   * Whether any of the parsers expect commands.
+   */
+  readonly hasCommands: boolean;
+  /**
+   * Whether any of the parsers expect arguments.
+   */
+  readonly hasArguments: boolean;
+}
 /**
  * Options for customizing error messages in the {@link or} parser.
  * @since 0.5.0
@@ -20,8 +39,27 @@ interface OrOptions {
 interface OrErrorOptions {
   /**
    * Custom error message when no parser matches.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { noMatch: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`인수가 필요합니다.`; // Korean: "Argument required"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  noMatch?: Message;
+  noMatch?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom error message for unexpected input.
    * Can be a static message or a function that receives the unexpected token.
@@ -306,8 +344,27 @@ interface LongestMatchOptions {
 interface LongestMatchErrorOptions {
   /**
    * Custom error message when no parser matches.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { noMatch: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`引数が必要です。`; // Japanese: "Argument required"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  noMatch?: Message;
+  noMatch?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom error message for unexpected input.
    * Can be a static message or a function that receives the unexpected token.
@@ -447,8 +504,27 @@ interface ObjectErrorOptions {
   readonly unexpectedInput?: Message | ((token: string) => Message);
   /**
    * Error message when end of input is reached unexpectedly.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { endOfInput: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   endOfInput: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`Argument manquant.`; // French: "Missing argument"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  readonly endOfInput?: Message;
+  readonly endOfInput?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom function to format suggestion messages.
    * If provided, this will be used instead of the default "Did you mean?"
@@ -1183,4 +1259,4 @@ declare function concat<TA extends readonly unknown[], TB extends readonly unkno
  */
 declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
 //#endregion
-export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };
+export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.d.ts

@@ -13,6 +13,25 @@ interface OrOptions {
    */
   errors?: OrErrorOptions;
 }
+/**
+ * Context information about what types of inputs are expected,
+ * used for generating contextual error messages.
+ * @since 0.9.0
+ */
+interface NoMatchContext {
+  /**
+   * Whether any of the parsers expect options.
+   */
+  readonly hasOptions: boolean;
+  /**
+   * Whether any of the parsers expect commands.
+   */
+  readonly hasCommands: boolean;
+  /**
+   * Whether any of the parsers expect arguments.
+   */
+  readonly hasArguments: boolean;
+}
 /**
  * Options for customizing error messages in the {@link or} parser.
  * @since 0.5.0
@@ -20,8 +39,27 @@ interface OrOptions {
 interface OrErrorOptions {
   /**
    * Custom error message when no parser matches.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { noMatch: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`인수가 필요합니다.`; // Korean: "Argument required"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  noMatch?: Message;
+  noMatch?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom error message for unexpected input.
    * Can be a static message or a function that receives the unexpected token.
@@ -306,8 +344,27 @@ interface LongestMatchOptions {
 interface LongestMatchErrorOptions {
   /**
    * Custom error message when no parser matches.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { noMatch: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   noMatch: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`引数が必要です。`; // Japanese: "Argument required"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  noMatch?: Message;
+  noMatch?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom error message for unexpected input.
    * Can be a static message or a function that receives the unexpected token.
@@ -447,8 +504,27 @@ interface ObjectErrorOptions {
   readonly unexpectedInput?: Message | ((token: string) => Message);
   /**
    * Error message when end of input is reached unexpectedly.
+   * Can be a static message or a function that receives context about what
+   * types of inputs are expected, allowing for more precise error messages.
+   *
+   * @example
+   * ```typescript
+   * // Static message (overrides all cases)
+   * { endOfInput: message`Invalid input.` }
+   *
+   * // Dynamic message based on context (for i18n, etc.)
+   * {
+   *   endOfInput: ({ hasOptions, hasCommands, hasArguments }) => {
+   *     if (hasArguments && !hasOptions && !hasCommands) {
+   *       return message`Argument manquant.`; // French: "Missing argument"
+   *     }
+   *     // ... other cases
+   *   }
+   * }
+   * ```
+   * @since 0.9.0 - Function form added
    */
-  readonly endOfInput?: Message;
+  readonly endOfInput?: Message | ((context: NoMatchContext) => Message);
   /**
    * Custom function to format suggestion messages.
    * If provided, this will be used instead of the default "Did you mean?"
@@ -1183,4 +1259,4 @@ declare function concat<TA extends readonly unknown[], TB extends readonly unkno
  */
 declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
 //#endregion
-export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };
+export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.js

@@ -1,9 +1,68 @@
 import { message, optionName, values } from "./message.js";
-import { extractOptionNames } from "./usage.js";
+import { extractArgumentMetavars, extractCommandNames, extractOptionNames } from "./usage.js";
 import { createErrorWithSuggestions } from "./suggestion.js";
 
 //#region src/constructs.ts
 /**
+* Extracts required (non-optional) usage terms from a usage array.
+* @param usage The usage to extract required terms from
+* @returns Usage containing only required (non-optional) terms
+*/
+function extractRequiredUsage(usage) {
+	const required = [];
+	for (const term of usage) if (term.type === "optional") continue;
+	else if (term.type === "exclusive") {
+		const requiredBranches = term.terms.map((branch) => extractRequiredUsage(branch)).filter((branch) => branch.length > 0);
+		if (requiredBranches.length > 0) required.push({
+			type: "exclusive",
+			terms: requiredBranches
+		});
+	} else if (term.type === "multiple") {
+		if (term.min > 0) {
+			const requiredTerms = extractRequiredUsage(term.terms);
+			if (requiredTerms.length > 0) required.push({
+				type: "multiple",
+				terms: requiredTerms,
+				min: term.min
+			});
+		}
+	} else required.push(term);
+	return required;
+}
+/**
+* Analyzes parsers to determine what types of inputs are expected.
+* @param parsers The parsers being combined
+* @returns Context about what types of inputs are expected
+*/
+function analyzeNoMatchContext(parsers) {
+	const combinedUsage = [{
+		type: "exclusive",
+		terms: parsers.map((p) => p.usage)
+	}];
+	const requiredUsage = extractRequiredUsage(combinedUsage);
+	return {
+		hasOptions: extractOptionNames(requiredUsage).size > 0,
+		hasCommands: extractCommandNames(requiredUsage).size > 0,
+		hasArguments: extractArgumentMetavars(requiredUsage).size > 0
+	};
+}
+/**
+* Generates a contextual error message based on what types of inputs
+* the parsers expect (options, commands, or arguments).
+* @param context Context about what types of inputs are expected
+* @returns An appropriate error message
+*/
+function generateNoMatchError(context) {
+	const { hasOptions, hasCommands, hasArguments } = context;
+	if (hasArguments && !hasOptions && !hasCommands) return message`Missing required argument.`;
+	else if (hasCommands && !hasOptions && !hasArguments) return message`No matching command found.`;
+	else if (hasOptions && !hasCommands && !hasArguments) return message`No matching option found.`;
+	else if (hasCommands && hasOptions && !hasArguments) return message`No matching option or command found.`;
+	else if (hasArguments && hasOptions && !hasCommands) return message`No matching option or argument found.`;
+	else if (hasArguments && hasCommands && !hasOptions) return message`No matching command or argument found.`;
+	else return message`No matching option, command, or argument found.`;
+}
+/**
 * @since 0.5.0
 */
 function or(...args) {
@@ -16,6 +75,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	const noMatchContext = analyzeNoMatchContext(parsers);
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -26,10 +86,14 @@ function or(...args) {
 		}],
 		initialState: void 0,
 		complete(state) {
-			if (state == null) return {
-				success: false,
-				error: options?.errors?.noMatch ?? message`No matching option or command found.`
-			};
+			if (state == null) {
+				const customNoMatch = options?.errors?.noMatch;
+				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				return {
+					success: false,
+					error
+				};
+			}
 			const [i, result] = state;
 			if (result.success) return parsers[i].complete(result.next.state);
 			return {
@@ -40,7 +104,10 @@ function or(...args) {
 		parse(context) {
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? message`No matching option or command found.` : (() => {
+				error: context.buffer.length < 1 ? (() => {
+					const customNoMatch = options?.errors?.noMatch;
+					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				})() : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
 					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
@@ -151,6 +218,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	const noMatchContext = analyzeNoMatchContext(parsers);
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -161,10 +229,14 @@ function longestMatch(...args) {
 		}],
 		initialState: void 0,
 		complete(state) {
-			if (state == null) return {
-				success: false,
-				error: options?.errors?.noMatch ?? message`No matching option or command found.`
-			};
+			if (state == null) {
+				const customNoMatch = options?.errors?.noMatch;
+				const error = customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				return {
+					success: false,
+					error
+				};
+			}
 			const [i, result] = state;
 			if (result.success) return parsers[i].complete(result.next.state);
 			return {
@@ -176,7 +248,10 @@ function longestMatch(...args) {
 			let bestMatch = null;
 			let error = {
 				consumed: 0,
-				error: context.buffer.length < 1 ? options?.errors?.noMatch ?? message`No matching option or command found.` : (() => {
+				error: context.buffer.length < 1 ? (() => {
+					const customNoMatch = options?.errors?.noMatch;
+					return customNoMatch ? typeof customNoMatch === "function" ? customNoMatch(noMatchContext) : customNoMatch : generateNoMatchError(noMatchContext);
+				})() : (() => {
 					const token = context.buffer[0];
 					const defaultMsg = message`Unexpected option or subcommand: ${optionName(token)}.`;
 					if (options?.errors?.unexpectedInput != null) return typeof options.errors.unexpectedInput === "function" ? options.errors.unexpectedInput(token) : options.errors.unexpectedInput;
@@ -242,6 +317,7 @@ function longestMatch(...args) {
 		},
 		getDocFragments(state, _defaultValue) {
 			let description;
+			let footer;
 			let fragments;
 			if (state.kind === "unavailable" || state.state == null) fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			else {
@@ -252,12 +328,14 @@ function longestMatch(...args) {
 						state: result.next.state
 					});
 					description = docResult.description;
+					footer = docResult.footer;
 					fragments = docResult.fragments;
 				} else fragments = parsers.flatMap((p) => p.getDocFragments({ kind: "unavailable" }).fragments);
 			}
 			return {
 				description,
-				fragments
+				fragments,
+				footer
 			};
 		}
 	};
@@ -275,6 +353,7 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	}
 	const parserPairs = Object.entries(parsers);
 	parserPairs.sort(([_, parserA], [__, parserB]) => parserB.priority - parserA.priority);
+	const noMatchContext = analyzeNoMatchContext(Object.values(parsers));
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -305,7 +384,10 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 					if (customMessage) return typeof customMessage === "function" ? customMessage(token) : customMessage;
 					const baseError = message`Unexpected option or argument: ${token}.`;
 					return createErrorWithSuggestions(baseError, token, context.usage, "both", options.errors?.suggestions);
-				})() : options.errors?.endOfInput ?? message`Expected an option or argument, but got end of input.`
+				})() : (() => {
+					const customEndOfInput = options.errors?.endOfInput;
+					return customEndOfInput ? typeof customEndOfInput === "function" ? customEndOfInput(noMatchContext) : customEndOfInput : generateNoMatchError(noMatchContext);
+				})()
 			};
 			let currentContext = context;
 			let anySuccess = false;

package/dist/facade.cjs

@@ -54,27 +54,41 @@ function createVersionParser(mode) {
 /**
 * Creates completion parsers based on the specified mode.
 */
-function createCompletionParser(mode, programName, availableShells) {
+function createCompletionParser(mode, programName, availableShells, name = "both") {
 	const shellList = [];
 	for (const shell in availableShells) {
 		if (shellList.length > 0) shellList.push(require_message.text(", "));
 		shellList.push(require_message.value(shell));
 	}
-	const completionCommand = require_primitives.command("completion", require_constructs.object({
+	const completionInner = require_constructs.object({
 		shell: require_modifiers.optional(require_primitives.argument(require_valueparser.string({ metavar: "SHELL" }), { description: require_message.message`Shell type (${shellList}). Generate completion script when used alone, or provide completions when followed by arguments.` })),
 		args: require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "ARG" }), { description: require_message.message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` }))
-	}), {
+	});
+	const commandName = name === "plural" ? "completions" : "completion";
+	const completionCommandConfig = {
 		brief: require_message.message`Generate shell completion script or provide completions.`,
 		description: require_message.message`Generate shell completion script or provide completions.`,
 		footer: require_message.message`Examples:
-  Bash:       ${require_message.commandLine(`eval "$(${programName} completion bash)"`)}
-  zsh:        ${require_message.commandLine(`eval "$(${programName} completion zsh)"`)}
-  fish:       ${require_message.commandLine(`eval "$(${programName} completion fish)"`)}
-  PowerShell: ${require_message.commandLine(`${programName} completion pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}
-  Nushell:    ${require_message.commandLine(`${programName} completion nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}
+  Bash:       ${require_message.commandLine(`eval "$(${programName} ${commandName} bash)"`)}
+  zsh:        ${require_message.commandLine(`eval "$(${programName} ${commandName} zsh)"`)}
+  fish:       ${require_message.commandLine(`eval "$(${programName} ${commandName} fish)"`)}
+  PowerShell: ${require_message.commandLine(`${programName} ${commandName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}
+  Nushell:    ${require_message.commandLine(`${programName} ${commandName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}
 `
-	});
-	const completionOption = require_primitives.option("--completion", require_valueparser.string({ metavar: "SHELL" }), { description: require_message.message`Generate shell completion script.` });
+	};
+	const completionCommands = [];
+	if (name === "singular" || name === "both") completionCommands.push(require_primitives.command("completion", completionInner, completionCommandConfig));
+	if (name === "plural" || name === "both") completionCommands.push(require_primitives.command("completions", completionInner, completionCommandConfig));
+	const completionCommand = require_constructs.longestMatch(...completionCommands);
+	const completionOptionNames = [];
+	if (name === "singular" || name === "both") completionOptionNames.push("--completion");
+	if (name === "plural" || name === "both") completionOptionNames.push("--completions");
+	const completionOptionArgs = [
+		...completionOptionNames,
+		require_valueparser.string({ metavar: "SHELL" }),
+		{ description: require_message.message`Generate shell completion script.` }
+	];
+	const completionOption = require_primitives.option(...completionOptionArgs);
 	switch (mode) {
 		case "command": return {
 			completionCommand,
@@ -412,6 +426,7 @@ function run(parser, programName, args, options = {}) {
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
 	const completionMode = options.completion?.mode ?? "both";
+	const completionName = options.completion?.name ?? "both";
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const defaultShells = {
 		bash: require_completion.bash,
@@ -438,20 +453,26 @@ function run(parser, programName, args, options = {}) {
 	const completionParsers = completion === "none" ? {
 		completionCommand: null,
 		completionOption: null
-	} : createCompletionParser(completion, programName, availableShells);
+	} : createCompletionParser(completion, programName, availableShells, completionName);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && args[0] === "completion" && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
-			if (arg.startsWith("--completion=")) {
-				const shell = arg.slice(13);
+			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
+			const pluralMatch = completionName === "plural" || completionName === "both" ? arg.startsWith("--completions=") : false;
+			if (singularMatch || pluralMatch) {
+				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
 				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
-			} else if (arg === "--completion" && i + 1 < args.length) {
-				const shell = args[i + 1];
-				const completionArgs = args.slice(i + 2);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+			} else {
+				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
+				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
+				if ((singularMatchExact || pluralMatchExact) && i + 1 < args.length) {
+					const shell = args[i + 1];
+					const completionArgs = args.slice(i + 2);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+				}
 			}
 		}
 	}
@@ -474,7 +495,7 @@ function run(parser, programName, args, options = {}) {
 			const versionAsCommand = version === "command" || version === "both";
 			const completionAsCommand = completion === "command" || completion === "both";
 			const requestedCommand = classified.commands[0];
-			if (requestedCommand === "completion" && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+			if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
 			else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
 			else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 			else {
@@ -494,7 +515,7 @@ function run(parser, programName, args, options = {}) {
 			}
 			const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) {
-				const isMetaCommandHelp = requestedCommand === "completion" || requestedCommand === "help" || requestedCommand === "version";
+				const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
 				const augmentedDoc = {
 					...doc,
 					brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,

package/dist/facade.d.cts

@@ -104,6 +104,16 @@ interface RunOptions<THelp, TError> {
      * @default `"both"`
      */
     readonly mode?: "command" | "option" | "both";
+    /**
+     * Determines whether to use singular or plural naming for completion command/option.
+     *
+     * - `"singular"`: Use `completion` / `--completion`
+     * - `"plural"`: Use `completions` / `--completions`
+     * - `"both"`: Use both singular and plural forms
+     *
+     * @default `"both"`
+     */
+    readonly name?: "singular" | "plural" | "both";
     /**
      * Available shell completions. By default, includes `bash`, `fish`, `nu`,
      * `pwsh`, and `zsh`. You can provide additional custom shell completions or

package/dist/facade.d.ts

@@ -104,6 +104,16 @@ interface RunOptions<THelp, TError> {
      * @default `"both"`
      */
     readonly mode?: "command" | "option" | "both";
+    /**
+     * Determines whether to use singular or plural naming for completion command/option.
+     *
+     * - `"singular"`: Use `completion` / `--completion`
+     * - `"plural"`: Use `completions` / `--completions`
+     * - `"both"`: Use both singular and plural forms
+     *
+     * @default `"both"`
+     */
+    readonly name?: "singular" | "plural" | "both";
     /**
      * Available shell completions. By default, includes `bash`, `fish`, `nu`,
      * `pwsh`, and `zsh`. You can provide additional custom shell completions or

package/dist/facade.js

@@ -54,27 +54,41 @@ function createVersionParser(mode) {
 /**
 * Creates completion parsers based on the specified mode.
 */
-function createCompletionParser(mode, programName, availableShells) {
+function createCompletionParser(mode, programName, availableShells, name = "both") {
 	const shellList = [];
 	for (const shell in availableShells) {
 		if (shellList.length > 0) shellList.push(text(", "));
 		shellList.push(value(shell));
 	}
-	const completionCommand = command("completion", object({
+	const completionInner = object({
 		shell: optional(argument(string({ metavar: "SHELL" }), { description: message`Shell type (${shellList}). Generate completion script when used alone, or provide completions when followed by arguments.` })),
 		args: multiple(argument(string({ metavar: "ARG" }), { description: message`Command line arguments for completion suggestions (used by shell integration; you usually don't need to provide this).` }))
-	}), {
+	});
+	const commandName = name === "plural" ? "completions" : "completion";
+	const completionCommandConfig = {
 		brief: message`Generate shell completion script or provide completions.`,
 		description: message`Generate shell completion script or provide completions.`,
 		footer: message`Examples:
-  Bash:       ${commandLine(`eval "$(${programName} completion bash)"`)}
-  zsh:        ${commandLine(`eval "$(${programName} completion zsh)"`)}
-  fish:       ${commandLine(`eval "$(${programName} completion fish)"`)}
-  PowerShell: ${commandLine(`${programName} completion pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}
-  Nushell:    ${commandLine(`${programName} completion nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}
+  Bash:       ${commandLine(`eval "$(${programName} ${commandName} bash)"`)}
+  zsh:        ${commandLine(`eval "$(${programName} ${commandName} zsh)"`)}
+  fish:       ${commandLine(`eval "$(${programName} ${commandName} fish)"`)}
+  PowerShell: ${commandLine(`${programName} ${commandName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}
+  Nushell:    ${commandLine(`${programName} ${commandName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}
 `
-	});
-	const completionOption = option("--completion", string({ metavar: "SHELL" }), { description: message`Generate shell completion script.` });
+	};
+	const completionCommands = [];
+	if (name === "singular" || name === "both") completionCommands.push(command("completion", completionInner, completionCommandConfig));
+	if (name === "plural" || name === "both") completionCommands.push(command("completions", completionInner, completionCommandConfig));
+	const completionCommand = longestMatch(...completionCommands);
+	const completionOptionNames = [];
+	if (name === "singular" || name === "both") completionOptionNames.push("--completion");
+	if (name === "plural" || name === "both") completionOptionNames.push("--completions");
+	const completionOptionArgs = [
+		...completionOptionNames,
+		string({ metavar: "SHELL" }),
+		{ description: message`Generate shell completion script.` }
+	];
+	const completionOption = option(...completionOptionArgs);
 	switch (mode) {
 		case "command": return {
 			completionCommand,
@@ -412,6 +426,7 @@ function run(parser, programName, args, options = {}) {
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
 	const completionMode = options.completion?.mode ?? "both";
+	const completionName = options.completion?.name ?? "both";
 	const onCompletion = options.completion?.onShow ?? (() => ({}));
 	const defaultShells = {
 		bash,
@@ -438,20 +453,26 @@ function run(parser, programName, args, options = {}) {
 	const completionParsers = completion === "none" ? {
 		completionCommand: null,
 		completionOption: null
-	} : createCompletionParser(completion, programName, availableShells);
+	} : createCompletionParser(completion, programName, availableShells, completionName);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && args[0] === "completion" && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && ((completionName === "singular" || completionName === "both" ? args[0] === "completion" : false) || (completionName === "plural" || completionName === "both" ? args[0] === "completions" : false)) && !hasHelpOption) return handleCompletion(args.slice(1), programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
-			if (arg.startsWith("--completion=")) {
-				const shell = arg.slice(13);
+			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
+			const pluralMatch = completionName === "plural" || completionName === "both" ? arg.startsWith("--completions=") : false;
+			if (singularMatch || pluralMatch) {
+				const shell = arg.slice(arg.indexOf("=") + 1);
 				const completionArgs = args.slice(i + 1);
 				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
-			} else if (arg === "--completion" && i + 1 < args.length) {
-				const shell = args[i + 1];
-				const completionArgs = args.slice(i + 2);
-				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+			} else {
+				const singularMatchExact = completionName === "singular" || completionName === "both" ? arg === "--completion" : false;
+				const pluralMatchExact = completionName === "plural" || completionName === "both" ? arg === "--completions" : false;
+				if ((singularMatchExact || pluralMatchExact) && i + 1 < args.length) {
+					const shell = args[i + 1];
+					const completionArgs = args.slice(i + 2);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth);
+				}
 			}
 		}
 	}
@@ -474,7 +495,7 @@ function run(parser, programName, args, options = {}) {
 			const versionAsCommand = version === "command" || version === "both";
 			const completionAsCommand = completion === "command" || completion === "both";
 			const requestedCommand = classified.commands[0];
-			if (requestedCommand === "completion" && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
+			if ((requestedCommand === "completion" || requestedCommand === "completions") && completionAsCommand && completionParsers.completionCommand) helpGeneratorParser = completionParsers.completionCommand;
 			else if (requestedCommand === "help" && helpAsCommand && helpParsers.helpCommand) helpGeneratorParser = helpParsers.helpCommand;
 			else if (requestedCommand === "version" && versionAsCommand && versionParsers.versionCommand) helpGeneratorParser = versionParsers.versionCommand;
 			else {
@@ -494,7 +515,7 @@ function run(parser, programName, args, options = {}) {
 			}
 			const doc = getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) {
-				const isMetaCommandHelp = requestedCommand === "completion" || requestedCommand === "help" || requestedCommand === "version";
+				const isMetaCommandHelp = (completionName === "singular" || completionName === "both" ? requestedCommand === "completion" : false) || (completionName === "plural" || completionName === "both" ? requestedCommand === "completions" : false) || requestedCommand === "help" || requestedCommand === "version";
 				const augmentedDoc = {
 					...doc,
 					brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,

package/dist/index.cjs

@@ -19,6 +19,7 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.constant = require_primitives.constant;
 exports.envVar = require_message.envVar;
+exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fish = require_completion.fish;

package/dist/index.d.cts

@@ -1,11 +1,11 @@
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
-import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
+import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.cjs";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Message, MessageFormatOptions, MessageTerm, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
-import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
+import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, 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 { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.js";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
-import { extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
+import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
@@ -9,4 +9,4 @@ import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, constant, envVar, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/parser.d.cts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/parser.d.ts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.js";
 import { ValueParserResult } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/usage.cjs

@@ -63,6 +63,38 @@ function extractCommandNames(usage) {
 	return names;
 }
 /**
+* Extracts all argument metavars from a Usage array.
+*
+* This function recursively traverses the usage structure and collects
+* all argument metavariable names, similar to {@link extractOptionNames}
+* and {@link extractCommandNames}.
+*
+* @param usage The usage structure to extract argument metavars from.
+* @returns A Set of all argument metavars found in the usage structure.
+*
+* @example
+* ```typescript
+* const usage: Usage = [
+*   { type: "argument", metavar: "FILE" },
+*   { type: "argument", metavar: "OUTPUT" },
+* ];
+* const metavars = extractArgumentMetavars(usage);
+* // metavars = Set(["FILE", "OUTPUT"])
+* ```
+* @since 0.9.0
+*/
+function extractArgumentMetavars(usage) {
+	const metavars = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "argument") metavars.add(term.metavar);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
+	}
+	traverseUsage(usage);
+	return metavars;
+}
+/**
 * Formats a usage description into a human-readable string representation
 * suitable for command-line help text.
 *
@@ -299,6 +331,7 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
+exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;

package/dist/usage.d.cts

@@ -158,6 +158,28 @@ declare function extractOptionNames(usage: Usage): Set<string>;
  * @since 0.7.0
  */
 declare function extractCommandNames(usage: Usage): Set<string>;
+/**
+ * Extracts all argument metavars from a Usage array.
+ *
+ * This function recursively traverses the usage structure and collects
+ * all argument metavariable names, similar to {@link extractOptionNames}
+ * and {@link extractCommandNames}.
+ *
+ * @param usage The usage structure to extract argument metavars from.
+ * @returns A Set of all argument metavars found in the usage structure.
+ *
+ * @example
+ * ```typescript
+ * const usage: Usage = [
+ *   { type: "argument", metavar: "FILE" },
+ *   { type: "argument", metavar: "OUTPUT" },
+ * ];
+ * const metavars = extractArgumentMetavars(usage);
+ * // metavars = Set(["FILE", "OUTPUT"])
+ * ```
+ * @since 0.9.0
+ */
+declare function extractArgumentMetavars(usage: Usage): Set<string>;
 /**
  * Options for formatting usage descriptions.
  */
@@ -256,4 +278,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/dist/usage.d.ts

@@ -158,6 +158,28 @@ declare function extractOptionNames(usage: Usage): Set<string>;
  * @since 0.7.0
  */
 declare function extractCommandNames(usage: Usage): Set<string>;
+/**
+ * Extracts all argument metavars from a Usage array.
+ *
+ * This function recursively traverses the usage structure and collects
+ * all argument metavariable names, similar to {@link extractOptionNames}
+ * and {@link extractCommandNames}.
+ *
+ * @param usage The usage structure to extract argument metavars from.
+ * @returns A Set of all argument metavars found in the usage structure.
+ *
+ * @example
+ * ```typescript
+ * const usage: Usage = [
+ *   { type: "argument", metavar: "FILE" },
+ *   { type: "argument", metavar: "OUTPUT" },
+ * ];
+ * const metavars = extractArgumentMetavars(usage);
+ * // metavars = Set(["FILE", "OUTPUT"])
+ * ```
+ * @since 0.9.0
+ */
+declare function extractArgumentMetavars(usage: Usage): Set<string>;
 /**
  * Options for formatting usage descriptions.
  */
@@ -256,4 +278,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/dist/usage.js

@@ -62,6 +62,38 @@ function extractCommandNames(usage) {
 	return names;
 }
 /**
+* Extracts all argument metavars from a Usage array.
+*
+* This function recursively traverses the usage structure and collects
+* all argument metavariable names, similar to {@link extractOptionNames}
+* and {@link extractCommandNames}.
+*
+* @param usage The usage structure to extract argument metavars from.
+* @returns A Set of all argument metavars found in the usage structure.
+*
+* @example
+* ```typescript
+* const usage: Usage = [
+*   { type: "argument", metavar: "FILE" },
+*   { type: "argument", metavar: "OUTPUT" },
+* ];
+* const metavars = extractArgumentMetavars(usage);
+* // metavars = Set(["FILE", "OUTPUT"])
+* ```
+* @since 0.9.0
+*/
+function extractArgumentMetavars(usage) {
+	const metavars = /* @__PURE__ */ new Set();
+	function traverseUsage(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) if (term.type === "argument") metavars.add(term.metavar);
+		else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
+		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
+	}
+	traverseUsage(usage);
+	return metavars;
+}
+/**
 * Formats a usage description into a human-readable string representation
 * suitable for command-line help text.
 *
@@ -298,4 +330,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.7.0-dev.150+59dd16c2",
+  "version": "0.7.0-dev.153+e7e0b894",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",