@optique/core 0.4.0-dev.54 → 0.4.0-dev.56

package/dist/doc.cjs

@@ -73,11 +73,19 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${entry.description == null ? "" : indentLines(require_message.formatMessage(entry.description, {
+			let description = entry.description == null ? "" : require_message.formatMessage(entry.description, {
 				colors: options.colors,
 				quotes: !options.colors,
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
-			}), termIndent + termWidth + 2)}\n`;
+			});
+			if (options.showDefault && entry.default != null) {
+				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const defaultText = `${prefix}${entry.default}${suffix}`;
+				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
+				description += formattedDefault;
+			}
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
 	if (page.footer != null) {

package/dist/doc.d.cts

@@ -69,6 +69,25 @@ interface DocFragments {
    */
   readonly fragments: readonly DocFragment[];
 }
+/**
+ * Configuration for customizing default value display formatting.
+ *
+ * @since 0.4.0
+ */
+interface ShowDefaultOptions {
+  /**
+   * Text to display before the default value.
+   *
+   * @default `" ["`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the default value.
+   *
+   * @default `"]"`
+   */
+  readonly suffix?: string;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -92,6 +111,30 @@ interface DocPageFormatOptions {
    * Maximum width of the entire formatted output.
    */
   maxWidth?: number;
+  /**
+   * Whether and how to display default values for options and arguments.
+   *
+   * - `boolean`: When `true`, displays defaults using format `[value]`
+   * - `ShowDefaultOptions`: Custom formatting with configurable prefix and suffix
+   *
+   * Default values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.4.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "[3000]"
+   * { showDefault: true }
+   *
+   * // Custom format - shows "(default: 3000)"
+   * { showDefault: { prefix: " (default: ", suffix: ")" } }
+   *
+   * // Custom format - shows " - defaults to 3000"
+   * { showDefault: { prefix: " - defaults to ", suffix: "" } }
+   * ```
+   */
+  showDefault?: boolean | ShowDefaultOptions;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -126,4 +169,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage };

package/dist/doc.d.ts

@@ -69,6 +69,25 @@ interface DocFragments {
    */
   readonly fragments: readonly DocFragment[];
 }
+/**
+ * Configuration for customizing default value display formatting.
+ *
+ * @since 0.4.0
+ */
+interface ShowDefaultOptions {
+  /**
+   * Text to display before the default value.
+   *
+   * @default `" ["`
+   */
+  readonly prefix?: string;
+  /**
+   * Text to display after the default value.
+   *
+   * @default `"]"`
+   */
+  readonly suffix?: string;
+}
 /**
  * Options for formatting a documentation page.
  */
@@ -92,6 +111,30 @@ interface DocPageFormatOptions {
    * Maximum width of the entire formatted output.
    */
   maxWidth?: number;
+  /**
+   * Whether and how to display default values for options and arguments.
+   *
+   * - `boolean`: When `true`, displays defaults using format `[value]`
+   * - `ShowDefaultOptions`: Custom formatting with configurable prefix and suffix
+   *
+   * Default values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.4.0
+   *
+   * @example
+   * ```typescript
+   * // Basic usage - shows "[3000]"
+   * { showDefault: true }
+   *
+   * // Custom format - shows "(default: 3000)"
+   * { showDefault: { prefix: " (default: ", suffix: ")" } }
+   *
+   * // Custom format - shows " - defaults to 3000"
+   * { showDefault: { prefix: " - defaults to ", suffix: "" } }
+   * ```
+   */
+  showDefault?: boolean | ShowDefaultOptions;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -126,4 +169,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage };

package/dist/doc.js

@@ -73,11 +73,19 @@ function formatDocPage(programName, page, options = {}) {
 				optionsSeparator: ", ",
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent
 			});
-			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${entry.description == null ? "" : indentLines(formatMessage(entry.description, {
+			let description = entry.description == null ? "" : formatMessage(entry.description, {
 				colors: options.colors,
 				quotes: !options.colors,
 				maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - termIndent - termWidth - 2
-			}), termIndent + termWidth + 2)}\n`;
+			});
+			if (options.showDefault && entry.default != null) {
+				const prefix = typeof options.showDefault === "object" ? options.showDefault.prefix ?? " [" : " [";
+				const suffix = typeof options.showDefault === "object" ? options.showDefault.suffix ?? "]" : "]";
+				const defaultText = `${prefix}${entry.default}${suffix}`;
+				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
+				description += formattedDefault;
+			}
+			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
 	if (page.footer != null) {

package/dist/facade.cjs

@@ -287,7 +287,7 @@ function run(parser, programName, args, options = {}) {
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
-	let { colors, maxWidth, aboveError = "usage", onError = () => {
+	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log } = options;
 	const help = options.help ? helpMode : "none";
@@ -336,7 +336,8 @@ function run(parser, programName, args, options = {}) {
 			const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) stdout(require_doc.formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				showDefault
 			}));
 			try {
 				return onHelp(0);
@@ -351,7 +352,8 @@ function run(parser, programName, args, options = {}) {
 		if (doc == null) aboveError = "usage";
 		else stderr(require_doc.formatDocPage(programName, doc, {
 			colors,
-			maxWidth
+			maxWidth,
+			showDefault
 		}));
 	}
 	if (aboveError === "usage") stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {

package/dist/facade.d.cts

@@ -1,3 +1,4 @@
+import { ShowDefaultOptions } from "./doc.cjs";
 import { InferValue, Parser } from "./parser.cjs";
 
 //#region src/facade.d.ts
@@ -20,6 +21,18 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Whether and how to display default values for options and arguments.
+   *
+   * - `boolean`: When `true`, displays defaults using format `[value]`
+   * - `ShowDefaultOptions`: Custom formatting with configurable prefix and suffix
+   *
+   * Default values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.4.0
+   */
+  readonly showDefault?: boolean | ShowDefaultOptions;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.d.ts

@@ -1,3 +1,4 @@
+import { ShowDefaultOptions } from "./doc.js";
 import { InferValue, Parser } from "./parser.js";
 
 //#region src/facade.d.ts
@@ -20,6 +21,18 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Whether and how to display default values for options and arguments.
+   *
+   * - `boolean`: When `true`, displays defaults using format `[value]`
+   * - `ShowDefaultOptions`: Custom formatting with configurable prefix and suffix
+   *
+   * Default values are automatically dimmed when `colors` is enabled.
+   *
+   * @default `false`
+   * @since 0.4.0
+   */
+  readonly showDefault?: boolean | ShowDefaultOptions;
   /**
    * Help configuration. When provided, enables help functionality.
    */

package/dist/facade.js

@@ -287,7 +287,7 @@ function run(parser, programName, args, options = {}) {
 	const versionMode = options.version?.mode ?? "option";
 	const versionValue = options.version?.value ?? "";
 	const onVersion = options.version?.onShow ?? (() => ({}));
-	let { colors, maxWidth, aboveError = "usage", onError = () => {
+	let { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log } = options;
 	const help = options.help ? helpMode : "none";
@@ -336,7 +336,8 @@ function run(parser, programName, args, options = {}) {
 			const doc = getDocPage(helpGeneratorParser, classified.commands);
 			if (doc != null) stdout(formatDocPage(programName, doc, {
 				colors,
-				maxWidth
+				maxWidth,
+				showDefault
 			}));
 			try {
 				return onHelp(0);
@@ -351,7 +352,8 @@ function run(parser, programName, args, options = {}) {
 		if (doc == null) aboveError = "usage";
 		else stderr(formatDocPage(programName, doc, {
 			colors,
-			maxWidth
+			maxWidth,
+			showDefault
 		}));
 	}
 	if (aboveError === "usage") stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.cjs";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
 import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, 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 { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, 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 };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
 import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, 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 { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, concat, constant, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.4.0-dev.54+e30f3e5c",
+  "version": "0.4.0-dev.56+2ae81fd7",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",