@optique/core 0.5.0 → 0.6.0-dev.102

package/dist/facade.js

@@ -1,11 +1,12 @@
-import { formatMessage, message, optionName } from "./message.js";
+import { formatMessage, message, optionName, text, value } from "./message.js";
 import { longestMatch, object } from "./constructs.js";
 import { formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
+import { bash, fish, pwsh, zsh } from "./completion.js";
 import { multiple, optional } from "./modifiers.js";
 import { string } from "./valueparser.js";
 import { argument, command, constant, flag } from "./primitives.js";
-import { getDocPage, parse } from "./parser.js";
+import { getDocPage, parse, suggest } from "./parser.js";
 
 //#region src/facade.ts
 /**
@@ -118,6 +119,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers) {
 					value: state
 				};
 			},
+			suggest(_context, prefix) {
+				if ("--help".startsWith(prefix)) return [{
+					kind: "literal",
+					text: "--help"
+				}];
+				return [];
+			},
 			getDocFragments(state) {
 				return helpParsers.helpOption?.getDocFragments(state) ?? { fragments: [] };
 			}
@@ -179,6 +187,13 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers) {
 					value: state
 				};
 			},
+			suggest(_context, prefix) {
+				if ("--version".startsWith(prefix)) return [{
+					kind: "literal",
+					text: "--version"
+				}];
+				return [];
+			},
 			getDocFragments(state) {
 				return versionParsers.versionOption?.getDocFragments(state) ?? { fragments: [] };
 			}
@@ -213,9 +228,9 @@ function classifyResult(result, args) {
 		type: "error",
 		error: result.error
 	};
-	const value = result.value;
-	if (typeof value === "object" && value != null && "help" in value && "version" in value) {
-		const parsedValue = value;
+	const value$1 = result.value;
+	if (typeof value$1 === "object" && value$1 != null && "help" in value$1 && "version" in value$1) {
+		const parsedValue = value$1;
 		const hasVersionOption = args.includes("--version");
 		const hasVersionCommand = args.length > 0 && args[0] === "version";
 		const hasHelpOption = args.includes("--help");
@@ -237,15 +252,59 @@ function classifyResult(result, args) {
 		if ((hasVersionOption || hasVersionCommand) && (parsedValue.version || parsedValue.versionFlag)) return { type: "version" };
 		return {
 			type: "success",
-			value: parsedValue.result ?? value
+			value: parsedValue.result ?? value$1
 		};
 	}
 	return {
 		type: "success",
-		value
+		value: value$1
 	};
 }
 /**
+* Handles shell completion requests.
+* @since 0.6.0
+*/
+function handleCompletion(completionArgs, programName, parser, stdout, stderr, onCompletion, onError, colors) {
+	if (completionArgs.length === 0) {
+		stderr("Error: Missing shell name for completion.\n");
+		stderr("Usage: " + programName + " completion <shell> [args...]\n");
+		return onError(1);
+	}
+	const shellName = completionArgs[0];
+	const args = completionArgs.slice(1);
+	const availableShells = {
+		bash,
+		fish,
+		pwsh,
+		zsh
+	};
+	const shell = availableShells[shellName];
+	if (!shell) {
+		const available = [];
+		for (const shell$1 in availableShells) {
+			if (available.length > 0) available.push(text(", "));
+			available.push(value(shell$1));
+		}
+		stderr(formatMessage(message`Error: Unsupported shell ${shellName}. Available shells: ${available}.`, {
+			colors,
+			quotes: !colors
+		}));
+		return onError(1);
+	}
+	if (args.length === 0) {
+		const script = shell.generateScript(programName, ["completion", shellName]);
+		stdout(script);
+	} else {
+		const suggestions = suggest(parser, args);
+		for (const chunk of shell.encodeSuggestions(suggestions)) stdout(chunk);
+	}
+	try {
+		return onCompletion(0);
+	} catch {
+		return onCompletion();
+	}
+}
+/**
 * Runs a parser against command-line arguments with built-in help and error
 * handling.
 *
@@ -275,14 +334,31 @@ function classifyResult(result, args) {
 * @throws {RunError} When parsing fails and no `onError` callback is provided.
 */
 function run(parser, programName, args, options = {}) {
+	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+		throw new RunError("Failed to parse command line arguments.");
+	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	const completionMode = options.completion?.mode ?? "both";
+	const onCompletion = options.completion?.onShow ?? (() => ({}));
+	if (options.completion) {
+		if ((completionMode === "command" || completionMode === "both") && args.length >= 1 && args[0] === "completion") return handleCompletion(args.slice(1), programName, parser, stdout, stderr, onCompletion, onError, colors);
+		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 completionArgs = args.slice(i + 1);
+				return handleCompletion([shell, ...completionArgs], programName, parser, stdout, stderr, onCompletion, onError, colors);
+			} 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, stdout, stderr, onCompletion, onError, colors);
+			}
+		}
+	}
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
-	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
-		throw new RunError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
 	const help = options.help ? helpMode : "none";
 	const version = options.version ? versionMode : "none";
 	const helpParsers = help === "none" ? {
@@ -345,36 +421,38 @@ function run(parser, programName, args, options = {}) {
 				return onHelp();
 			}
 		}
-		case "error": break;
-	}
-	if (aboveError === "help") {
-		const doc = getDocPage(args.length < 1 ? augmentedParser : parser, args);
-		if (doc == null) aboveError = "usage";
-		else {
-			const augmentedDoc = {
-				...doc,
-				brief: brief ?? doc.brief,
-				description: description ?? doc.description,
-				footer: footer ?? doc.footer
-			};
-			stderr(formatDocPage(programName, augmentedDoc, {
+		case "error": {
+			if (aboveError === "help") {
+				const doc = getDocPage(args.length < 1 ? augmentedParser : parser, args);
+				if (doc == null) aboveError = "usage";
+				else {
+					const augmentedDoc = {
+						...doc,
+						brief: brief ?? doc.brief,
+						description: description ?? doc.description,
+						footer: footer ?? doc.footer
+					};
+					stderr(formatDocPage(programName, augmentedDoc, {
+						colors,
+						maxWidth,
+						showDefault
+					}));
+				}
+			}
+			if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
+				colors,
+				maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
+				expandCommands: true
+			}), 7)}`);
+			const errorMessage = formatMessage(classified.error, {
 				colors,
-				maxWidth,
-				showDefault
-			}));
+				quotes: !colors
+			});
+			stderr(`Error: ${errorMessage}`);
+			return onError(1);
 		}
+		default: throw new RunError("Unexpected parse result type");
 	}
-	if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {
-		colors,
-		maxWidth: maxWidth == null ? void 0 : maxWidth - 7,
-		expandCommands: true
-	}), 7)}`);
-	const errorMessage = formatMessage(classified.error, {
-		colors,
-		quotes: !colors
-	});
-	stderr(`Error: ${errorMessage}`);
-	return onError(1);
 }
 /**
 * An error class used to indicate that the command line arguments
@@ -386,8 +464,8 @@ var RunError = class extends Error {
 		this.name = "RunError";
 	}
 };
-function indentLines(text, indent) {
-	return text.split("\n").join("\n" + " ".repeat(indent));
+function indentLines(text$1, indent) {
+	return text$1.split("\n").join("\n" + " ".repeat(indent));
 }
 
 //#endregion

package/dist/index.cjs

@@ -2,6 +2,7 @@ const require_message = require('./message.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
+const require_completion = require('./completion.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
@@ -11,11 +12,13 @@ const require_facade = require('./facade.cjs');
 exports.RunError = require_facade.RunError;
 exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;
+exports.bash = require_completion.bash;
 exports.choice = require_valueparser.choice;
 exports.command = require_primitives.command;
 exports.concat = require_constructs.concat;
 exports.constant = require_primitives.constant;
 exports.envVar = require_message.envVar;
+exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;
 exports.formatDocPage = require_doc.formatDocPage;
@@ -41,12 +44,15 @@ exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
+exports.pwsh = require_completion.pwsh;
 exports.run = require_facade.run;
 exports.string = require_valueparser.string;
+exports.suggest = require_parser.suggest;
 exports.text = require_message.text;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;
 exports.uuid = require_valueparser.uuid;
 exports.value = require_message.value;
 exports.values = require_message.values;
-exports.withDefault = require_modifiers.withDefault;
+exports.withDefault = require_modifiers.withDefault;
+exports.zsh = require_completion.zsh;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/modifiers.cjs

@@ -44,6 +44,13 @@ function optional(parser) {
 			};
 			return parser.complete(state[0]);
 		},
+		suggest(context, prefix) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
@@ -127,6 +134,13 @@ function withDefault(parser, defaultValue, options) {
 			}
 			return parser.complete(state[0]);
 		},
+		suggest(context, prefix) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
@@ -200,6 +214,9 @@ function map(parser, transform) {
 			};
 			return result;
 		},
+		suggest(context, prefix) {
+			return parser.suggest(context, prefix);
+		},
 		getDocFragments(state, _defaultValue) {
 			return parser.getDocFragments(state, void 0);
 		}
@@ -282,6 +299,13 @@ function multiple(parser, options = {}) {
 				value: result
 			};
 		},
+		suggest(context, prefix) {
+			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
 				kind: "available",

package/dist/modifiers.js

@@ -44,6 +44,13 @@ function optional(parser) {
 			};
 			return parser.complete(state[0]);
 		},
+		suggest(context, prefix) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
@@ -127,6 +134,13 @@ function withDefault(parser, defaultValue, options) {
 			}
 			return parser.complete(state[0]);
 		},
+		suggest(context, prefix) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, upperDefaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
 				kind: "available",
@@ -200,6 +214,9 @@ function map(parser, transform) {
 			};
 			return result;
 		},
+		suggest(context, prefix) {
+			return parser.suggest(context, prefix);
+		},
 		getDocFragments(state, _defaultValue) {
 			return parser.getDocFragments(state, void 0);
 		}
@@ -282,6 +299,13 @@ function multiple(parser, options = {}) {
 				value: result
 			};
 		},
+		suggest(context, prefix) {
+			const innerState = context.state.length > 0 ? context.state.at(-1) : parser.initialState;
+			return parser.suggest({
+				...context,
+				state: innerState
+			}, prefix);
+		},
 		getDocFragments(state, defaultValue) {
 			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
 				kind: "available",

package/dist/parser.cjs

@@ -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.
@@ -143,5 +188,6 @@ exports.option = require_primitives.option;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
 exports.parse = parse;
+exports.suggest = suggest;
 exports.tuple = require_constructs.tuple;
 exports.withDefault = require_modifiers.withDefault;

package/dist/parser.d.cts

@@ -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 };