@optique/core 0.5.0 → 0.6.0-dev.102

package/dist/parser.d.ts

@@ -78,6 +78,19 @@ interface Parser<TValue, TState> {
    *          it should return an error message.
    */
   complete(state: TState): ValueParserResult<TValue>;
+  /**
+   * Generates next-step suggestions based on the current context
+   * and an optional prefix.  This can be used to provide shell completion
+   * suggestions or to guide users in constructing valid commands.
+   * @param context The context of the parser, which includes the input buffer
+   *                and the current state.
+   * @param prefix A prefix string that can be used to filter suggestions.
+   *               Can be an empty string if no prefix is provided.
+   * @returns An iterable of {@link Suggestion} objects, each containing
+   *          a suggestion text and an optional description.
+   * @since 0.6.0
+   */
+  suggest(context: ParserContext<TState>, prefix: string): Iterable<Suggestion>;
   /**
    * Generates a documentation fragment for this parser, which can be used
    * to describe the parser's usage, description, and default value.
@@ -113,6 +126,51 @@ interface ParserContext<TState> {
    */
   readonly optionsTerminated: boolean;
 }
+/**
+ * Represents a suggestion for command-line completion or guidance.
+ * @since 0.6.0
+ */
+type Suggestion = {
+  /**
+   * A literal text suggestion.
+   */
+  readonly kind: "literal";
+  /**
+   * The suggestion text that can be used for completion or guidance.
+   */
+  readonly text: string;
+  /**
+   * An optional description providing additional context
+   * or information about the suggestion.
+   */
+  readonly description?: Message;
+} | {
+  /**
+   * A file system completion suggestion that uses native shell completion.
+   */
+  readonly kind: "file";
+  /**
+   * The current prefix/pattern for fallback when native completion is unavailable.
+   */
+  readonly pattern?: string;
+  /**
+   * The type of file system entries to complete.
+   */
+  readonly type: "file" | "directory" | "any";
+  /**
+   * File extensions to filter by (e.g., [".ts", ".js"]).
+   */
+  readonly extensions?: readonly string[];
+  /**
+   * Whether to include hidden files (those starting with a dot).
+   */
+  readonly includeHidden?: boolean;
+  /**
+   * An optional description providing additional context
+   * or information about the suggestion.
+   */
+  readonly description?: Message;
+};
 /**
  * A discriminated union type representing the result of a parser operation.
  * It can either indicate a successful parse with the next state and context,
@@ -193,6 +251,35 @@ type Result<T> = {
  *          failure.
  */
 declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
+/**
+ * Generates command-line suggestions based on current parsing state.
+ * This function processes the input arguments up to the last argument,
+ * then calls the parser's suggest method with the remaining prefix.
+ * @template T The type of the value produced by the parser.
+ * @param parser The {@link Parser} to use for generating suggestions.
+ * @param args The array of command-line arguments including the partial
+ *             argument to complete.  The last element is treated as
+ *             the prefix for suggestions.
+ * @returns An array of {@link Suggestion} objects containing completion
+ *          candidates.
+ * @example
+ * ```typescript
+ * const parser = object({
+ *   verbose: option("-v", "--verbose"),
+ *   format: option("-f", "--format", choice(["json", "yaml"]))
+ * });
+ *
+ * // Get suggestions for options starting with "--"
+ * const suggestions = suggest(parser, ["--"]);
+ * // Returns: [{ text: "--verbose" }, { text: "--format" }]
+ *
+ * // Get suggestions after parsing some arguments
+ * const suggestions2 = suggest(parser, ["-v", "--format="]);
+ * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
+ * ```
+ * @since 0.6.0
+ */
+declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string, ...readonly string[]]): readonly Suggestion[];
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -228,4 +315,4 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/parser.js

@@ -48,6 +48,51 @@ function parse(parser, args) {
 	};
 }
 /**
+* Generates command-line suggestions based on current parsing state.
+* This function processes the input arguments up to the last argument,
+* then calls the parser's suggest method with the remaining prefix.
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @returns An array of {@link Suggestion} objects containing completion
+*          candidates.
+* @example
+* ```typescript
+* const parser = object({
+*   verbose: option("-v", "--verbose"),
+*   format: option("-f", "--format", choice(["json", "yaml"]))
+* });
+*
+* // Get suggestions for options starting with "--"
+* const suggestions = suggest(parser, ["--"]);
+* // Returns: [{ text: "--verbose" }, { text: "--format" }]
+*
+* // Get suggestions after parsing some arguments
+* const suggestions2 = suggest(parser, ["-v", "--format="]);
+* // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
+* ```
+* @since 0.6.0
+*/
+function suggest(parser, args) {
+	const allButLast = args.slice(0, -1);
+	const prefix = args[args.length - 1];
+	let context = {
+		buffer: allButLast,
+		optionsTerminated: false,
+		state: parser.initialState
+	};
+	while (context.buffer.length > 0) {
+		const result = parser.parse(context);
+		if (!result.success) return Array.from(parser.suggest(context, prefix));
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer[0] === previousBuffer[0]) return [];
+	}
+	return Array.from(parser.suggest(context, prefix));
+}
+/**
 * Generates a documentation page for a parser based on its current state after
 * attempting to parse the provided arguments. This function is useful for
 * creating help documentation that reflects the current parsing context.
@@ -126,4 +171,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/primitives.cjs

@@ -27,6 +27,9 @@ function constant(value) {
 				value: state
 			};
 		},
+		suggest(_context, _prefix) {
+			return [];
+		},
 		getDocFragments(_state, _defaultValue) {
 			return { fragments: [] };
 		}
@@ -199,6 +202,51 @@ function option(...args) {
 				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : require_message.message`${require_message.optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			const equalsIndex = prefix.indexOf("=");
+			if (equalsIndex >= 0) {
+				const optionPart = prefix.slice(0, equalsIndex);
+				const valuePart = prefix.slice(equalsIndex + 1);
+				if (optionNames$1.includes(optionPart)) {
+					if (valueParser && valueParser.suggest) {
+						const valueSuggestions = valueParser.suggest(valuePart);
+						for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") suggestions.push({
+							kind: "literal",
+							text: `${optionPart}=${suggestion.text}`,
+							description: suggestion.description
+						});
+						else suggestions.push({
+							kind: "literal",
+							text: `${optionPart}=${suggestion.pattern || ""}`,
+							description: suggestion.description
+						});
+					}
+				}
+			} else {
+				if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+					for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+						if (prefix === "-" && optionName$1.length !== 2) continue;
+						suggestions.push({
+							kind: "literal",
+							text: optionName$1
+						});
+					}
+				}
+				if (valueParser && valueParser.suggest) {
+					let shouldSuggestValues = false;
+					if (context.buffer.length > 0) {
+						const lastToken = context.buffer[context.buffer.length - 1];
+						if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
+					} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
+					if (shouldSuggestValues) {
+						const valueSuggestions = valueParser.suggest(prefix);
+						suggestions.push(...valueSuggestions);
+					}
+				}
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -358,6 +406,19 @@ function flag(...args) {
 				error: require_message.message`${require_message.optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
+		suggest(_context, prefix) {
+			const suggestions = [];
+			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+					if (prefix === "-" && optionName$1.length !== 2) continue;
+					suggestions.push({
+						kind: "literal",
+						text: optionName$1
+					});
+				}
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, _defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -452,6 +513,14 @@ function argument(valueParser, options = {}) {
 				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : require_message.message`${require_message.metavar(valueParser.metavar)}: ${state.error}`
 			};
 		},
+		suggest(_context, prefix) {
+			const suggestions = [];
+			if (valueParser.suggest) {
+				const valueSuggestions = valueParser.suggest(prefix);
+				suggestions.push(...valueSuggestions);
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -559,6 +628,29 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? require_message.message`Invalid command state during completion.`
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			if (context.state === void 0) {
+				if (name.startsWith(prefix)) suggestions.push({
+					kind: "literal",
+					text: name,
+					...options.description && { description: options.description }
+				});
+			} else if (context.state[0] === "matched") {
+				const innerSuggestions = parser.suggest({
+					...context,
+					state: parser.initialState
+				}, prefix);
+				suggestions.push(...innerSuggestions);
+			} else if (context.state[0] === "parsing") {
+				const innerSuggestions = parser.suggest({
+					...context,
+					state: context.state[1]
+				}, prefix);
+				suggestions.push(...innerSuggestions);
+			}
+			return suggestions;
+		},
 		getDocFragments(state, defaultValue) {
 			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,

package/dist/primitives.js

@@ -27,6 +27,9 @@ function constant(value) {
 				value: state
 			};
 		},
+		suggest(_context, _prefix) {
+			return [];
+		},
 		getDocFragments(_state, _defaultValue) {
 			return { fragments: [] };
 		}
@@ -199,6 +202,51 @@ function option(...args) {
 				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			const equalsIndex = prefix.indexOf("=");
+			if (equalsIndex >= 0) {
+				const optionPart = prefix.slice(0, equalsIndex);
+				const valuePart = prefix.slice(equalsIndex + 1);
+				if (optionNames$1.includes(optionPart)) {
+					if (valueParser && valueParser.suggest) {
+						const valueSuggestions = valueParser.suggest(valuePart);
+						for (const suggestion of valueSuggestions) if (suggestion.kind === "literal") suggestions.push({
+							kind: "literal",
+							text: `${optionPart}=${suggestion.text}`,
+							description: suggestion.description
+						});
+						else suggestions.push({
+							kind: "literal",
+							text: `${optionPart}=${suggestion.pattern || ""}`,
+							description: suggestion.description
+						});
+					}
+				}
+			} else {
+				if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+					for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+						if (prefix === "-" && optionName$1.length !== 2) continue;
+						suggestions.push({
+							kind: "literal",
+							text: optionName$1
+						});
+					}
+				}
+				if (valueParser && valueParser.suggest) {
+					let shouldSuggestValues = false;
+					if (context.buffer.length > 0) {
+						const lastToken = context.buffer[context.buffer.length - 1];
+						if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
+					} else if (context.state === void 0 && context.buffer.length === 0) shouldSuggestValues = true;
+					if (shouldSuggestValues) {
+						const valueSuggestions = valueParser.suggest(prefix);
+						suggestions.push(...valueSuggestions);
+					}
+				}
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -358,6 +406,19 @@ function flag(...args) {
 				error: message`${optionNames(optionNames$1)}: ${state.error}`
 			};
 		},
+		suggest(_context, prefix) {
+			const suggestions = [];
+			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+					if (prefix === "-" && optionName$1.length !== 2) continue;
+					suggestions.push({
+						kind: "literal",
+						text: optionName$1
+					});
+				}
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, _defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -452,6 +513,14 @@ function argument(valueParser, options = {}) {
 				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${state.error}`
 			};
 		},
+		suggest(_context, prefix) {
+			const suggestions = [];
+			if (valueParser.suggest) {
+				const valueSuggestions = valueParser.suggest(prefix);
+				suggestions.push(...valueSuggestions);
+			}
+			return suggestions;
+		},
 		getDocFragments(_state, defaultValue) {
 			const fragments = [{
 				type: "entry",
@@ -559,6 +628,29 @@ function command(name, parser, options = {}) {
 				error: options.errors?.invalidState ?? message`Invalid command state during completion.`
 			};
 		},
+		suggest(context, prefix) {
+			const suggestions = [];
+			if (context.state === void 0) {
+				if (name.startsWith(prefix)) suggestions.push({
+					kind: "literal",
+					text: name,
+					...options.description && { description: options.description }
+				});
+			} else if (context.state[0] === "matched") {
+				const innerSuggestions = parser.suggest({
+					...context,
+					state: parser.initialState
+				}, prefix);
+				suggestions.push(...innerSuggestions);
+			} else if (context.state[0] === "parsing") {
+				const innerSuggestions = parser.suggest({
+					...context,
+					state: context.state[1]
+				}, prefix);
+				suggestions.push(...innerSuggestions);
+			}
+			return suggestions;
+		},
 		getDocFragments(state, defaultValue) {
 			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
 				description: options.description,

package/dist/valueparser.cjs

@@ -39,6 +39,16 @@ function choice(values, options = {}) {
 		},
 		format(value) {
 			return value;
+		},
+		suggest(prefix) {
+			const normalizedPrefix = options.caseInsensitive ? prefix.toLowerCase() : prefix;
+			return values.filter((value) => {
+				const normalizedValue = options.caseInsensitive ? value.toLowerCase() : value;
+				return normalizedValue.startsWith(normalizedPrefix);
+			}).map((value) => ({
+				kind: "literal",
+				text: value
+			}));
 		}
 	};
 }
@@ -236,6 +246,15 @@ function url(options = {}) {
 		},
 		format(value) {
 			return value.href;
+		},
+		*suggest(prefix) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes("://")) for (const protocol of allowedProtocols) {
+				const cleanProtocol = protocol.replace(/:+$/, "");
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) yield {
+					kind: "literal",
+					text: `${cleanProtocol}://`
+				};
+			}
 		}
 	};
 }
@@ -270,6 +289,236 @@ function locale(options = {}) {
 		},
 		format(value) {
 			return value.baseName;
+		},
+		*suggest(prefix) {
+			const commonLocales = [
+				"en",
+				"en-US",
+				"en-GB",
+				"en-CA",
+				"en-AU",
+				"en-NZ",
+				"en-IE",
+				"en-ZA",
+				"en-IN",
+				"es",
+				"es-ES",
+				"es-MX",
+				"es-AR",
+				"es-CL",
+				"es-CO",
+				"es-PE",
+				"es-VE",
+				"es-EC",
+				"es-GT",
+				"es-CU",
+				"es-BO",
+				"es-DO",
+				"es-HN",
+				"es-PY",
+				"es-SV",
+				"es-NI",
+				"es-CR",
+				"es-PA",
+				"es-UY",
+				"es-PR",
+				"fr",
+				"fr-FR",
+				"fr-CA",
+				"fr-BE",
+				"fr-CH",
+				"fr-LU",
+				"fr-MC",
+				"de",
+				"de-DE",
+				"de-AT",
+				"de-CH",
+				"de-BE",
+				"de-LU",
+				"de-LI",
+				"it",
+				"it-IT",
+				"it-CH",
+				"it-SM",
+				"it-VA",
+				"pt",
+				"pt-BR",
+				"pt-PT",
+				"pt-AO",
+				"pt-MZ",
+				"pt-CV",
+				"pt-GW",
+				"pt-ST",
+				"pt-TL",
+				"ru",
+				"ru-RU",
+				"ru-BY",
+				"ru-KZ",
+				"ru-KG",
+				"ru-MD",
+				"uk",
+				"uk-UA",
+				"be",
+				"be-BY",
+				"bg",
+				"bg-BG",
+				"cs",
+				"cs-CZ",
+				"sk",
+				"sk-SK",
+				"sl",
+				"sl-SI",
+				"hr",
+				"hr-HR",
+				"sr",
+				"sr-RS",
+				"mk",
+				"mk-MK",
+				"ja",
+				"ja-JP",
+				"ko",
+				"ko-KR",
+				"zh",
+				"zh-CN",
+				"zh-TW",
+				"zh-HK",
+				"zh-SG",
+				"zh-MO",
+				"ar",
+				"ar-SA",
+				"ar-AE",
+				"ar-BH",
+				"ar-DZ",
+				"ar-EG",
+				"ar-IQ",
+				"ar-JO",
+				"ar-KW",
+				"ar-LB",
+				"ar-LY",
+				"ar-MA",
+				"ar-OM",
+				"ar-QA",
+				"ar-SY",
+				"ar-TN",
+				"ar-YE",
+				"hi",
+				"hi-IN",
+				"bn",
+				"bn-BD",
+				"bn-IN",
+				"ur",
+				"ur-PK",
+				"ta",
+				"ta-IN",
+				"te",
+				"te-IN",
+				"mr",
+				"mr-IN",
+				"gu",
+				"gu-IN",
+				"kn",
+				"kn-IN",
+				"ml",
+				"ml-IN",
+				"pa",
+				"pa-IN",
+				"tr",
+				"tr-TR",
+				"tr-CY",
+				"pl",
+				"pl-PL",
+				"nl",
+				"nl-NL",
+				"nl-BE",
+				"nl-SR",
+				"sv",
+				"sv-SE",
+				"sv-FI",
+				"da",
+				"da-DK",
+				"no",
+				"no-NO",
+				"nb",
+				"nb-NO",
+				"nn",
+				"nn-NO",
+				"fi",
+				"fi-FI",
+				"is",
+				"is-IS",
+				"el",
+				"el-GR",
+				"el-CY",
+				"hu",
+				"hu-HU",
+				"ro",
+				"ro-RO",
+				"et",
+				"et-EE",
+				"lv",
+				"lv-LV",
+				"lt",
+				"lt-LT",
+				"mt",
+				"mt-MT",
+				"ga",
+				"ga-IE",
+				"cy",
+				"cy-GB",
+				"eu",
+				"eu-ES",
+				"ca",
+				"ca-ES",
+				"ca-AD",
+				"th",
+				"th-TH",
+				"vi",
+				"vi-VN",
+				"id",
+				"id-ID",
+				"ms",
+				"ms-MY",
+				"ms-BN",
+				"ms-SG",
+				"tl",
+				"tl-PH",
+				"km",
+				"km-KH",
+				"my",
+				"my-MM",
+				"lo",
+				"lo-LA",
+				"si",
+				"si-LK",
+				"ne",
+				"ne-NP",
+				"sw",
+				"sw-TZ",
+				"sw-KE",
+				"am",
+				"am-ET",
+				"ha",
+				"ha-NG",
+				"yo",
+				"yo-NG",
+				"ig",
+				"ig-NG",
+				"zu",
+				"zu-ZA",
+				"xh",
+				"xh-ZA",
+				"af",
+				"af-ZA",
+				"he",
+				"he-IL",
+				"fa",
+				"fa-IR",
+				"fa-AF"
+			];
+			for (const locale$1 of commonLocales) if (locale$1.toLowerCase().startsWith(prefix.toLowerCase())) yield {
+				kind: "literal",
+				text: locale$1
+			};
 		}
 	};
 }