@optique/core 0.10.0-dev.369 → 0.10.0-dev.374

package/dist/doc.cjs

@@ -93,6 +93,35 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
+			if (options.showChoices && entry.choices != null) {
+				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
+				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
+				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;
+				const terms = Array.isArray(entry.choices) ? entry.choices : [];
+				let truncatedTerms = terms;
+				let truncated = false;
+				if (maxItems < Infinity) {
+					let valueCount = 0;
+					let cutIndex = terms.length;
+					for (let i = 0; i < terms.length; i++) if (terms[i].type === "value") {
+						valueCount++;
+						if (valueCount > maxItems) {
+							cutIndex = i > 0 && terms[i - 1].type === "text" ? i - 1 : i;
+							truncated = true;
+							break;
+						}
+					}
+					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), require_message.text(", ...")];
+				}
+				const choicesDisplay = require_message.formatMessage(truncatedTerms, {
+					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					quotes: false
+				});
+				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
+				description += formattedChoices;
+			}
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
@@ -142,14 +171,14 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	return output;
 }
-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));
 }
-function ansiAwareRightPad(text, length, char = " ") {
+function ansiAwareRightPad(text$1, length, char = " ") {
 	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
-	const strippedText = text.replace(ansiEscapeCodeRegex, "");
-	if (strippedText.length >= length) return text;
-	return text + char.repeat(length - strippedText.length);
+	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
+	if (strippedText.length >= length) return text$1;
+	return text$1 + char.repeat(length - strippedText.length);
 }
 
 //#endregion

package/dist/doc.d.cts

@@ -25,6 +25,14 @@ interface DocEntry {
    * specified.
    */
   readonly default?: Message;
+  /**
+   * An optional list of valid choices for the entry, formatted as a
+   * comma-separated {@link Message}.  When present and the `showChoices`
+   * formatting option is enabled, this is appended to the entry description.
+   *
+   * @since 0.10.0
+   */
+  readonly choices?: Message;
 }
 /**
  * A section in a document that groups related entries together.
@@ -114,6 +122,38 @@ interface ShowDefaultOptions {
    */
   readonly suffix?: string;
 }
+/**
+ * Configuration for customizing choices display formatting.
+ *
+ * @since 0.10.0
+ */
+interface ShowChoicesOptions {
+  /**
+   * Text to display before the choices list.
+   *
+   * @default `" ("`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the choices list.
+   *
+   * @default `")"`
+   */
+  readonly suffix?: string;
+  /**
+   * Label text to display before the individual choice values.
+   *
+   * @default `"choices: "`
+   */
+  readonly label?: string;
+  /**
+   * Maximum number of choice values to display before truncating with
+   * `...`.  Set to `Infinity` to show all choices.
+   *
+   * @default `8`
+   */
+  readonly maxItems?: number;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -161,6 +201,33 @@ interface DocPageFormatOptions {
    * ```
    */
   showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display valid choices for options and arguments
+   * backed by enumerated value parsers (e.g., `choice()`).
+   *
+   * - `boolean`: When `true`, displays choices using format
+   *   `(choices: a, b, c)`
+   * - `ShowChoicesOptions`: Custom formatting with configurable prefix,
+   *   suffix, label, and maximum number of items
+   *
+   * Choice values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.10.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "(choices: json, yaml, xml)"
+   * { showChoices: true }
+   *
+   * // Custom format - shows "{json | yaml | xml}"
+   * { showChoices: { prefix: " {", suffix: "}", label: "" } }
+   *
+   * // Limit displayed choices
+   * { showChoices: { maxItems: 3 } }
+   * ```
+   */
+  showChoices?: boolean | ShowChoicesOptions;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -195,4 +262,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage };

package/dist/doc.d.ts

@@ -25,6 +25,14 @@ interface DocEntry {
    * specified.
    */
   readonly default?: Message;
+  /**
+   * An optional list of valid choices for the entry, formatted as a
+   * comma-separated {@link Message}.  When present and the `showChoices`
+   * formatting option is enabled, this is appended to the entry description.
+   *
+   * @since 0.10.0
+   */
+  readonly choices?: Message;
 }
 /**
  * A section in a document that groups related entries together.
@@ -114,6 +122,38 @@ interface ShowDefaultOptions {
    */
   readonly suffix?: string;
 }
+/**
+ * Configuration for customizing choices display formatting.
+ *
+ * @since 0.10.0
+ */
+interface ShowChoicesOptions {
+  /**
+   * Text to display before the choices list.
+   *
+   * @default `" ("`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the choices list.
+   *
+   * @default `")"`
+   */
+  readonly suffix?: string;
+  /**
+   * Label text to display before the individual choice values.
+   *
+   * @default `"choices: "`
+   */
+  readonly label?: string;
+  /**
+   * Maximum number of choice values to display before truncating with
+   * `...`.  Set to `Infinity` to show all choices.
+   *
+   * @default `8`
+   */
+  readonly maxItems?: number;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -161,6 +201,33 @@ interface DocPageFormatOptions {
    * ```
    */
   showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display valid choices for options and arguments
+   * backed by enumerated value parsers (e.g., `choice()`).
+   *
+   * - `boolean`: When `true`, displays choices using format
+   *   `(choices: a, b, c)`
+   * - `ShowChoicesOptions`: Custom formatting with configurable prefix,
+   *   suffix, label, and maximum number of items
+   *
+   * Choice values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.10.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "(choices: json, yaml, xml)"
+   * { showChoices: true }
+   *
+   * // Custom format - shows "{json | yaml | xml}"
+   * { showChoices: { prefix: " {", suffix: "}", label: "" } }
+   *
+   * // Limit displayed choices
+   * { showChoices: { maxItems: 3 } }
+   * ```
+   */
+  showChoices?: boolean | ShowChoicesOptions;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -195,4 +262,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage };

package/dist/doc.js

@@ -1,4 +1,4 @@
-import { formatMessage } from "./message.js";
+import { formatMessage, text } from "./message.js";
 import { formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
@@ -93,6 +93,35 @@ function formatDocPage(programName, page, options = {}) {
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}
+			if (options.showChoices && entry.choices != null) {
+				const prefix = typeof options.showChoices === "object" ? options.showChoices.prefix ?? " (" : " (";
+				const suffix = typeof options.showChoices === "object" ? options.showChoices.suffix ?? ")" : ")";
+				const label = typeof options.showChoices === "object" ? options.showChoices.label ?? "choices: " : "choices: ";
+				const maxItems = typeof options.showChoices === "object" ? options.showChoices.maxItems ?? 8 : 8;
+				const terms = Array.isArray(entry.choices) ? entry.choices : [];
+				let truncatedTerms = terms;
+				let truncated = false;
+				if (maxItems < Infinity) {
+					let valueCount = 0;
+					let cutIndex = terms.length;
+					for (let i = 0; i < terms.length; i++) if (terms[i].type === "value") {
+						valueCount++;
+						if (valueCount > maxItems) {
+							cutIndex = i > 0 && terms[i - 1].type === "text" ? i - 1 : i;
+							truncated = true;
+							break;
+						}
+					}
+					if (truncated) truncatedTerms = [...terms.slice(0, cutIndex), text(", ...")];
+				}
+				const choicesDisplay = formatMessage(truncatedTerms, {
+					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					quotes: false
+				});
+				const choicesText = `${prefix}${label}${choicesDisplay}${suffix}`;
+				const formattedChoices = options.colors ? `\x1b[2m${choicesText}\x1b[0m` : choicesText;
+				description += formattedChoices;
+			}
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
@@ -142,14 +171,14 @@ function formatDocPage(programName, page, options = {}) {
 	}
 	return output;
 }
-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));
 }
-function ansiAwareRightPad(text, length, char = " ") {
+function ansiAwareRightPad(text$1, length, char = " ") {
 	const ansiEscapeCodeRegex = /\x1B\[[0-9;]*[a-zA-Z]/g;
-	const strippedText = text.replace(ansiEscapeCodeRegex, "");
-	if (strippedText.length >= length) return text;
-	return text + char.repeat(length - strippedText.length);
+	const strippedText = text$1.replace(ansiEscapeCodeRegex, "");
+	if (strippedText.length >= length) return text$1;
+	return text$1 + char.repeat(length - strippedText.length);
 }
 
 //#endregion

package/dist/facade.cjs

@@ -288,9 +288,26 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		completion: require_primitives.constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return require_constructs.longestMatch(parsers[0], parsers[1]);
-	else return require_constructs.longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = require_constructs.longestMatch(parsers[0], parsers[1]);
+	else combined = require_constructs.longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -434,7 +451,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -602,7 +619,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
-							showDefault
+							showDefault,
+							showChoices
 						}));
 					}
 					try {
@@ -632,7 +650,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(require_doc.formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
-							showDefault
+							showDefault,
+							showChoices
 						}));
 					}
 					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {

package/dist/facade.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { ShowDefaultOptions } from "./doc.cjs";
+import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.cjs";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.cjs";
 import { ShellCompletion } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
@@ -112,6 +112,21 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display valid choices for options and arguments
+   * backed by enumerated value parsers (e.g., `choice()`).
+   *
+   * - `boolean`: When `true`, displays choices using format
+   *   `(choices: a, b, c)`
+   * - `ShowChoicesOptions`: Custom formatting with configurable prefix,
+   *   suffix, label, and maximum number of items
+   *
+   * Choice values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.10.0
+   */
+  readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { ShowDefaultOptions } from "./doc.js";
+import { ShowChoicesOptions, ShowDefaultOptions } from "./doc.js";
 import { InferMode, InferValue, Mode, ModeValue, Parser } from "./parser.js";
 import { ShellCompletion } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
@@ -112,6 +112,21 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly showDefault?: boolean | ShowDefaultOptions;
+  /**
+   * Whether and how to display valid choices for options and arguments
+   * backed by enumerated value parsers (e.g., `choice()`).
+   *
+   * - `boolean`: When `true`, displays choices using format
+   *   `(choices: a, b, c)`
+   * - `ShowChoicesOptions`: Custom formatting with configurable prefix,
+   *   suffix, label, and maximum number of items
+   *
+   * Choice values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.10.0
+   */
+  readonly showChoices?: boolean | ShowChoicesOptions;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.js

@@ -288,9 +288,26 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 		completion: constant(false),
 		result: originalParser
 	}));
+	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return longestMatch(parsers[0], parsers[1]);
-	else return longestMatch(...parsers);
+	let combined;
+	if (parsers.length === 2) combined = longestMatch(parsers[0], parsers[1]);
+	else combined = longestMatch(...parsers);
+	const topUsage = combined.usage[0];
+	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
+		const terms = [...topUsage.terms];
+		const [mainTerm] = terms.splice(mainParserIndex, 1);
+		const lenientCount = (helpParsers.helpOption ? 1 : 0) + (versionParsers.versionOption ? 1 : 0);
+		terms.splice(lenientCount, 0, mainTerm);
+		combined = {
+			...combined,
+			usage: [{
+				...topUsage,
+				terms
+			}]
+		};
+	}
+	return combined;
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -434,7 +451,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		args = argsOrOptions;
 		options = optionsParam ?? {};
 	}
-	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
+	const { colors, maxWidth, showDefault, showChoices, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
@@ -602,7 +619,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
-							showDefault
+							showDefault,
+							showChoices
 						}));
 					}
 					try {
@@ -632,7 +650,8 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(formatDocPage(programName, augmentedDoc, {
 							colors,
 							maxWidth,
-							showDefault
+							showDefault,
+							showChoices
 						}));
 					}
 					if (effectiveAboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.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 { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.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 { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CompletionHelpVisibility, CompletionName, ExtractRequiredOptions, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CompletionHelpVisibility, CompletionName, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/primitives.cjs

@@ -464,6 +464,7 @@ function option(...args) {
 				fragments: [],
 				description: options.description
 			};
+			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -472,7 +473,8 @@ function option(...args) {
 					metavar: valueParser?.metavar
 				},
 				description: options.description,
-				default: defaultValue != null && valueParser != null ? require_message.message`${valueParser.format(defaultValue)}` : void 0
+				default: defaultValue != null && valueParser != null ? require_message.message`${valueParser.format(defaultValue)}` : void 0,
+				choices: choicesMessage
 			}];
 			return {
 				fragments,
@@ -790,11 +792,13 @@ function argument(valueParser, options = {}) {
 				fragments: [],
 				description: options.description
 			};
+			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? require_message.valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
 			const fragments = [{
 				type: "entry",
 				term,
 				description: options.description,
-				default: defaultValue == null ? void 0 : require_message.message`${valueParser.format(defaultValue)}`
+				default: defaultValue == null ? void 0 : require_message.message`${valueParser.format(defaultValue)}`,
+				choices: choicesMessage
 			}];
 			return {
 				fragments,

package/dist/primitives.js

@@ -1,4 +1,4 @@
-import { message, metavar, optionName, optionNames } from "./message.js";
+import { message, metavar, optionName, optionNames, valueSet } from "./message.js";
 import { createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, dependencyId, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, suggestWithDependency } from "./dependency.js";
 import { extractCommandNames, extractOptionNames } from "./usage.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, findSimilar } from "./suggestion.js";
@@ -464,6 +464,7 @@ function option(...args) {
 				fragments: [],
 				description: options.description
 			};
+			const choicesMessage = valueParser?.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
 			const fragments = [{
 				type: "entry",
 				term: {
@@ -472,7 +473,8 @@ function option(...args) {
 					metavar: valueParser?.metavar
 				},
 				description: options.description,
-				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0
+				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0,
+				choices: choicesMessage
 			}];
 			return {
 				fragments,
@@ -790,11 +792,13 @@ function argument(valueParser, options = {}) {
 				fragments: [],
 				description: options.description
 			};
+			const choicesMessage = valueParser.choices != null && valueParser.choices.length > 0 ? valueSet(valueParser.choices.map((c) => valueParser.format(c)), { type: "unit" }) : void 0;
 			const fragments = [{
 				type: "entry",
 				term,
 				description: options.description,
-				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`
+				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`,
+				choices: choicesMessage
 			}];
 			return {
 				fragments,

package/dist/valueparser.cjs

@@ -23,6 +23,7 @@ function choice(choices, options = {}) {
 		return {
 			$mode: "sync",
 			metavar,
+			choices,
 			parse(input) {
 				const parsed = Number(input);
 				if (Number.isNaN(parsed)) return {
@@ -56,6 +57,7 @@ function choice(choices, options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		choices,
 		parse(input) {
 			const normalizedInput = stringOptions.caseInsensitive ? input.toLowerCase() : input;
 			const index = normalizedValues.indexOf(normalizedInput);

package/dist/valueparser.d.cts

@@ -59,6 +59,16 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @since 0.6.0
    */
   suggest?(prefix: string): ModeIterable<M, Suggestion>;
+  /**
+   * An optional array of valid choices for this parser.  When present,
+   * indicates that this parser accepts only a fixed set of values, which
+   * can be displayed in help output via the `showChoices` formatting option.
+   *
+   * This field is populated automatically by the {@link choice} function.
+   *
+   * @since 0.10.0
+   */
+  readonly choices?: readonly T[];
 }
 /**
  * Result type returned by {@link ValueParser#parse}.

package/dist/valueparser.d.ts

@@ -59,6 +59,16 @@ interface ValueParser<M extends Mode = "sync", T = unknown> {
    * @since 0.6.0
    */
   suggest?(prefix: string): ModeIterable<M, Suggestion>;
+  /**
+   * An optional array of valid choices for this parser.  When present,
+   * indicates that this parser accepts only a fixed set of values, which
+   * can be displayed in help output via the `showChoices` formatting option.
+   *
+   * This field is populated automatically by the {@link choice} function.
+   *
+   * @since 0.10.0
+   */
+  readonly choices?: readonly T[];
 }
 /**
  * Result type returned by {@link ValueParser#parse}.

package/dist/valueparser.js

@@ -23,6 +23,7 @@ function choice(choices, options = {}) {
 		return {
 			$mode: "sync",
 			metavar,
+			choices,
 			parse(input) {
 				const parsed = Number(input);
 				if (Number.isNaN(parsed)) return {
@@ -56,6 +57,7 @@ function choice(choices, options = {}) {
 	return {
 		$mode: "sync",
 		metavar,
+		choices,
 		parse(input) {
 			const normalizedInput = stringOptions.caseInsensitive ? input.toLowerCase() : input;
 			const index = normalizedValues.indexOf(normalizedInput);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.369+ceed7dcf",
+  "version": "0.10.0-dev.374+981b7fab",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",