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

package/dist/constructs.cjs

@@ -242,6 +242,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 +253,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
 			};
 		}
 	};

package/dist/constructs.js

@@ -242,6 +242,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 +253,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
 			};
 		}
 	};

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/package.json

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