@optique/core 0.8.0 → 0.8.2

package/dist/constructs.cjs

@@ -4,6 +4,27 @@ const require_suggestion = require('./suggestion.cjs');
 
 //#region src/constructs.ts
 /**
+* Checks if the given token is an option name that requires a value
+* (i.e., has a metavar) within the given usage terms.
+* @param usage The usage terms to search through.
+* @param token The token to check.
+* @returns `true` if the token is an option that requires a value, `false` otherwise.
+*/
+function isOptionRequiringValue(usage, token) {
+	function traverse(terms) {
+		if (!terms || !Array.isArray(terms)) return false;
+		for (const term of terms) if (term.type === "option") {
+			if (term.metavar && term.names.includes(token)) return true;
+		} else if (term.type === "optional" || term.type === "multiple") {
+			if (traverse(term.terms)) return true;
+		} else if (term.type === "exclusive") {
+			for (const exclusiveUsage of term.terms) if (traverse(exclusiveUsage)) return true;
+		}
+		return false;
+	}
+	return traverse(usage);
+}
+/**
 * 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
@@ -442,6 +463,16 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		},
 		suggest(context, prefix) {
 			const suggestions = [];
+			if (context.buffer.length > 0) {
+				const lastToken = context.buffer[context.buffer.length - 1];
+				for (const [field, parser] of parserPairs) if (isOptionRequiringValue(parser.usage, lastToken)) {
+					const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+					return Array.from(parser.suggest({
+						...context,
+						state: fieldState
+					}, prefix));
+				}
+			}
 			for (const [field, parser] of parserPairs) {
 				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
 				const fieldSuggestions = parser.suggest({

package/dist/constructs.js

@@ -4,6 +4,27 @@ import { createErrorWithSuggestions, deduplicateSuggestions } from "./suggestion
 
 //#region src/constructs.ts
 /**
+* Checks if the given token is an option name that requires a value
+* (i.e., has a metavar) within the given usage terms.
+* @param usage The usage terms to search through.
+* @param token The token to check.
+* @returns `true` if the token is an option that requires a value, `false` otherwise.
+*/
+function isOptionRequiringValue(usage, token) {
+	function traverse(terms) {
+		if (!terms || !Array.isArray(terms)) return false;
+		for (const term of terms) if (term.type === "option") {
+			if (term.metavar && term.names.includes(token)) return true;
+		} else if (term.type === "optional" || term.type === "multiple") {
+			if (traverse(term.terms)) return true;
+		} else if (term.type === "exclusive") {
+			for (const exclusiveUsage of term.terms) if (traverse(exclusiveUsage)) return true;
+		}
+		return false;
+	}
+	return traverse(usage);
+}
+/**
 * 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
@@ -442,6 +463,16 @@ function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 		},
 		suggest(context, prefix) {
 			const suggestions = [];
+			if (context.buffer.length > 0) {
+				const lastToken = context.buffer[context.buffer.length - 1];
+				for (const [field, parser] of parserPairs) if (isOptionRequiringValue(parser.usage, lastToken)) {
+					const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
+					return Array.from(parser.suggest({
+						...context,
+						state: fieldState
+					}, prefix));
+				}
+			}
 			for (const [field, parser] of parserPairs) {
 				const fieldState = context.state && typeof context.state === "object" && field in context.state ? context.state[field] : parser.initialState;
 				const fieldSuggestions = parser.suggest({

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, completionMode) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
 	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 completionArg = completionMode === "option" ? "--completion" : "completion";
+		const usePlural = completionName === "plural";
+		const completionArg = completionMode === "option" ? usePlural ? "--completions" : "--completion" : usePlural ? "completions" : "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
 	} else {
@@ -457,7 +458,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, completionMode);
+		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, completionName);
 		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;
@@ -465,14 +466,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, completionMode);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 			} 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, completionMode);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 				}
 			}
 		}

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, completionMode) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName) {
 	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 completionArg = completionMode === "option" ? "--completion" : "completion";
+		const usePlural = completionName === "plural";
+		const completionArg = completionMode === "option" ? usePlural ? "--completions" : "--completion" : usePlural ? "completions" : "completion";
 		const script = shell.generateScript(programName, [completionArg, shellName]);
 		stdout(script);
 	} else {
@@ -457,7 +458,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, completionMode);
+		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, completionName);
 		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;
@@ -465,14 +466,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, completionMode);
+				return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 			} 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, completionMode);
+					return handleCompletion([shell, ...completionArgs], programName, parser, completionParsers.completionCommand, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionMode, completionName);
 				}
 			}
 		}

package/dist/modifiers.d.cts

@@ -81,7 +81,7 @@ declare class WithDefaultError extends Error {
  *          or the default value if the wrapped parser fails to match
  *          (union type {@link TValue} | {@link TDefault}).
  */
-declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
+declare function withDefault<TValue, TState, const TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -100,7 +100,7 @@ declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<T
  *          (union type {@link TValue} | {@link TDefault}).
  * @since 0.5.0
  */
-declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
+declare function withDefault<TValue, TState, const TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving

package/dist/modifiers.d.ts

@@ -81,7 +81,7 @@ declare class WithDefaultError extends Error {
  *          or the default value if the wrapped parser fails to match
  *          (union type {@link TValue} | {@link TDefault}).
  */
-declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
+declare function withDefault<TValue, TState, const TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -100,7 +100,7 @@ declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<T
  *          (union type {@link TValue} | {@link TDefault}).
  * @since 0.5.0
  */
-declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
+declare function withDefault<TValue, TState, const TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",