@optique/core 0.7.0-dev.152 → 0.7.0-dev.155

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;
@@ -278,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: [],
@@ -308,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;
@@ -278,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: [],
@@ -308,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

@@ -343,7 +343,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	if (!shellName) {
@@ -375,7 +375,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		return onError(1);
 	}
 	if (args.length === 0) {
-		const script = shell.generateScript(programName, ["completion", shellName]);
+		const completionArg = completionMode === "option" ? "--completion" : "completion";
+		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
 	} else {
 		const suggestions = require_parser.suggest(parser, args);
@@ -456,7 +457,7 @@ function run(parser, programName, args, options = {}) {
 	} : createCompletionParser(completion, programName, availableShells, completionName);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		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 === "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, completionMode);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -464,14 +465,14 @@ function run(parser, programName, args, options = {}) {
 			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);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode);
 			} 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);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode);
 				}
 			}
 		}

package/dist/facade.js

@@ -343,7 +343,7 @@ function classifyResult(result, args) {
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	if (!shellName) {
@@ -375,7 +375,8 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		return onError(1);
 	}
 	if (args.length === 0) {
-		const script = shell.generateScript(programName, ["completion", shellName]);
+		const completionArg = completionMode === "option" ? "--completion" : "completion";
+		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
 	} else {
 		const suggestions = suggest(parser, args);
@@ -456,7 +457,7 @@ function run(parser, programName, args, options = {}) {
 	} : createCompletionParser(completion, programName, availableShells, completionName);
 	if (options.completion) {
 		const hasHelpOption = args.includes("--help");
-		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 === "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, completionMode);
 		if (completionMode === "option" || completionMode === "both") for (let i = 0; i < args.length; i++) {
 			const arg = args[i];
 			const singularMatch = completionName === "singular" || completionName === "both" ? arg.startsWith("--completion=") : false;
@@ -464,14 +465,14 @@ function run(parser, programName, args, options = {}) {
 			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);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode);
 			} 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);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode);
 				}
 			}
 		}

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.152+14108c27",
+  "version": "0.7.0-dev.155+ff7366f7",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",