@optique/core 0.5.0-dev.64 → 0.5.0-dev.65

package/dist/doc.cjs

@@ -81,7 +81,10 @@ function formatDocPage(programName, page, options = {}) {
 			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 defaultText = `${prefix}${require_message.formatMessage(entry.default, {
+					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					quotes: !options.colors
+				})}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}

package/dist/doc.d.cts

@@ -24,7 +24,7 @@ interface DocEntry {
    * indicate what the default behavior is if the command or option is not
    * specified.
    */
-  readonly default?: string;
+  readonly default?: Message;
 }
 /**
  * A section in a document that groups related entries together.

package/dist/doc.d.ts

@@ -24,7 +24,7 @@ interface DocEntry {
    * indicate what the default behavior is if the command or option is not
    * specified.
    */
-  readonly default?: string;
+  readonly default?: Message;
 }
 /**
  * A section in a document that groups related entries together.

package/dist/doc.js

@@ -81,7 +81,10 @@ function formatDocPage(programName, page, options = {}) {
 			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 defaultText = `${prefix}${formatMessage(entry.default, {
+					colors: options.colors ? { resetSuffix: "\x1B[2m" } : false,
+					quotes: !options.colors
+				})}${suffix}`;
 				const formattedDefault = options.colors ? `\x1b[2m${defaultText}\x1b[0m` : defaultText;
 				description += formattedDefault;
 			}

package/dist/index.d.cts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, mess
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.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, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, 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, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, 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 { 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, 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 };

package/dist/index.d.ts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, mess
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.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, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, 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, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, 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 { 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, 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 };

package/dist/message.cjs

@@ -134,8 +134,11 @@ function envVar(envVar$1) {
 * @returns A formatted string representation of the message.
 */
 function formatMessage(msg, options = {}) {
-	const useColors = options.colors ?? false;
+	const colorConfig = options.colors ?? false;
+	const useColors = typeof colorConfig === "boolean" ? colorConfig : true;
+	const resetSuffix = typeof colorConfig === "object" ? colorConfig.resetSuffix ?? "" : "";
 	const useQuotes = options.quotes ?? true;
+	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
 		for (const term of msg) if (term.type === "text") while (true) {
@@ -149,7 +152,7 @@ function formatMessage(msg, options = {}) {
 		else if (term.type === "optionName") {
 			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
 			yield {
-				text: useColors ? `\x1b[3m${name}\x1b[0m` : name,
+				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
 				width: name.length
 			};
 		} else if (term.type === "optionNames") {
@@ -161,7 +164,7 @@ function formatMessage(msg, options = {}) {
 					width: 1
 				};
 				yield {
-					text: useColors ? `\x1b[3m${name}\x1b[0m` : name,
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
 					width: name.length
 				};
 				i++;
@@ -169,13 +172,13 @@ function formatMessage(msg, options = {}) {
 		} else if (term.type === "metavar") {
 			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
 			yield {
-				text: useColors ? `\x1b[1m${metavar$1}\x1b[0m` : metavar$1,
+				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
 				width: metavar$1.length
 			};
 		} else if (term.type === "value") {
 			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
 			yield {
-				text: useColors ? `\x1b[32m${value$1}\x1b[0m` : value$1,
+				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
 				width: value$1.length
 			};
 		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
@@ -185,14 +188,14 @@ function formatMessage(msg, options = {}) {
 			};
 			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}\x1b[0m` : value$1 : value$1,
+				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
 				width: value$1.length
 			};
 		}
 		else if (term.type === "envVar") {
 			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
 			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}\x1b[0m` : envVar$1,
+				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
 				width: envVar$1.length
 			};
 		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);

package/dist/message.d.cts

@@ -191,9 +191,21 @@ interface MessageFormatOptions {
    * Whether to use colors in the formatted message.  If `true`,
    * the formatted message will include ANSI escape codes for colors.
    * If `false`, the message will be plain text without colors.
+   *
+   * Can also be an object with additional color options:
+   *
+   * - `resetSuffix`: String to append after each ANSI reset sequence (`\x1b[0m`)
+   *   to maintain parent styling context.
+   *
    * @default `false`
    */
-  readonly colors?: boolean;
+  readonly colors?: boolean | {
+    /**
+     * String to append after each ANSI reset sequence to maintain
+     * parent styling context (e.g., `"\x1b[2m"` for dim text).
+     */
+    readonly resetSuffix?: string;
+  };
   /**
    * Whether to use quotes around values in the formatted message.
    * If `true`, values will be wrapped in quotes (e.g., `"value"`).

package/dist/message.d.ts

@@ -191,9 +191,21 @@ interface MessageFormatOptions {
    * Whether to use colors in the formatted message.  If `true`,
    * the formatted message will include ANSI escape codes for colors.
    * If `false`, the message will be plain text without colors.
+   *
+   * Can also be an object with additional color options:
+   *
+   * - `resetSuffix`: String to append after each ANSI reset sequence (`\x1b[0m`)
+   *   to maintain parent styling context.
+   *
    * @default `false`
    */
-  readonly colors?: boolean;
+  readonly colors?: boolean | {
+    /**
+     * String to append after each ANSI reset sequence to maintain
+     * parent styling context (e.g., `"\x1b[2m"` for dim text).
+     */
+    readonly resetSuffix?: string;
+  };
   /**
    * Whether to use quotes around values in the formatted message.
    * If `true`, values will be wrapped in quotes (e.g., `"value"`).

package/dist/message.js

@@ -133,8 +133,11 @@ function envVar(envVar$1) {
 * @returns A formatted string representation of the message.
 */
 function formatMessage(msg, options = {}) {
-	const useColors = options.colors ?? false;
+	const colorConfig = options.colors ?? false;
+	const useColors = typeof colorConfig === "boolean" ? colorConfig : true;
+	const resetSuffix = typeof colorConfig === "object" ? colorConfig.resetSuffix ?? "" : "";
 	const useQuotes = options.quotes ?? true;
+	const resetSequence = `\x1b[0m${resetSuffix}`;
 	function* stream() {
 		const wordPattern = /\s*\S+\s*/g;
 		for (const term of msg) if (term.type === "text") while (true) {
@@ -148,7 +151,7 @@ function formatMessage(msg, options = {}) {
 		else if (term.type === "optionName") {
 			const name = useQuotes ? `\`${term.optionName}\`` : term.optionName;
 			yield {
-				text: useColors ? `\x1b[3m${name}\x1b[0m` : name,
+				text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
 				width: name.length
 			};
 		} else if (term.type === "optionNames") {
@@ -160,7 +163,7 @@ function formatMessage(msg, options = {}) {
 					width: 1
 				};
 				yield {
-					text: useColors ? `\x1b[3m${name}\x1b[0m` : name,
+					text: useColors ? `\x1b[3m${name}${resetSequence}` : name,
 					width: name.length
 				};
 				i++;
@@ -168,13 +171,13 @@ function formatMessage(msg, options = {}) {
 		} else if (term.type === "metavar") {
 			const metavar$1 = useQuotes ? `\`${term.metavar}\`` : term.metavar;
 			yield {
-				text: useColors ? `\x1b[1m${metavar$1}\x1b[0m` : metavar$1,
+				text: useColors ? `\x1b[1m${metavar$1}${resetSequence}` : metavar$1,
 				width: metavar$1.length
 			};
 		} else if (term.type === "value") {
 			const value$1 = useQuotes ? `${JSON.stringify(term.value)}` : term.value;
 			yield {
-				text: useColors ? `\x1b[32m${value$1}\x1b[0m` : value$1,
+				text: useColors ? `\x1b[32m${value$1}${resetSequence}` : value$1,
 				width: value$1.length
 			};
 		} else if (term.type === "values") for (let i = 0; i < term.values.length; i++) {
@@ -184,14 +187,14 @@ function formatMessage(msg, options = {}) {
 			};
 			const value$1 = useQuotes ? JSON.stringify(term.values[i]) : term.values[i];
 			yield {
-				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}\x1b[0m` : value$1 : value$1,
+				text: useColors ? i <= 0 ? `\x1b[32m${value$1}` : i + 1 >= term.values.length ? `${value$1}${resetSequence}` : value$1 : value$1,
 				width: value$1.length
 			};
 		}
 		else if (term.type === "envVar") {
 			const envVar$1 = useQuotes ? `\`${term.envVar}\`` : term.envVar;
 			yield {
-				text: useColors ? `\x1b[1;4m${envVar$1}\x1b[0m` : envVar$1,
+				text: useColors ? `\x1b[1;4m${envVar$1}${resetSequence}` : envVar$1,
 				width: envVar$1.length
 			};
 		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);

package/dist/parser.cjs

@@ -209,7 +209,7 @@ function option(...args) {
 					metavar: valueParser?.metavar
 				},
 				description: options.description,
-				default: defaultValue != null && valueParser != null ? valueParser.format(defaultValue) : void 0
+				default: defaultValue != null && valueParser != null ? require_message.message`${valueParser.format(defaultValue)}` : void 0
 			}];
 			return {
 				fragments,
@@ -458,7 +458,7 @@ function argument(valueParser, options = {}) {
 				type: "entry",
 				term,
 				description: options.description,
-				default: defaultValue == null ? void 0 : valueParser.format(defaultValue)
+				default: defaultValue == null ? void 0 : require_message.message`${valueParser.format(defaultValue)}`
 			}];
 			return {
 				fragments,
@@ -556,22 +556,7 @@ var WithDefaultError = class extends Error {
 		this.name = "WithDefaultError";
 	}
 };
-/**
-* Creates a parser that makes another parser use a default value when it fails
-* to match or consume input. This is similar to {@link optional}, but instead
-* of returning `undefined` when the wrapped parser doesn't match, it returns
-* a specified default value.
-* @template TValue The type of the value returned by the wrapped parser.
-* @template TState The type of the state used by the wrapped parser.
-* @template TDefault The type of the default value.
-* @param parser The {@link Parser} to wrap with default behavior.
-* @param defaultValue The default value to return when the wrapped parser
-*                     doesn't match or consume input. Can be a value of type
-*                     {@link TDefault} or a function that returns such a value.
-* @returns A {@link Parser} that produces either the result of the wrapped parser
-*          or the default value if the wrapped parser fails to match (union type {@link TValue} | {@link TDefault}).
-*/
-function withDefault(parser, defaultValue) {
+function withDefault(parser, defaultValue, options) {
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -616,7 +601,22 @@ function withDefault(parser, defaultValue) {
 				kind: "available",
 				state: state.state[0]
 			};
-			return parser.getDocFragments(innerState, upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
+			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			const fragments = parser.getDocFragments(innerState, actualDefaultValue);
+			if (options?.message) {
+				const modifiedFragments = fragments.fragments.map((fragment) => {
+					if (fragment.type === "entry") return {
+						...fragment,
+						default: options.message
+					};
+					return fragment;
+				});
+				return {
+					...fragments,
+					fragments: modifiedFragments
+				};
+			}
+			return fragments;
 		}
 	};
 }

package/dist/parser.d.cts

@@ -276,6 +276,26 @@ declare function argument<T>(valueParser: ValueParser<T>, options?: ArgumentOpti
  *          or `undefined` if the wrapped parser fails to match.
  */
 declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parser<TValue | undefined, [TState] | undefined>;
+/**
+ * Options for the {@link withDefault} parser.
+ */
+interface WithDefaultOptions {
+  /**
+   * Custom message to display in help output instead of the formatted default value.
+   * This allows showing descriptive text like "SERVICE_URL environment variable"
+   * instead of the actual default value.
+   *
+   * @example
+   * ```typescript
+   * withDefault(
+   *   option("--url", url()),
+   *   process.env["SERVICE_URL"],
+   *   { message: message`${envVar("SERVICE_URL")} environment variable` }
+   * )
+   * ```
+   */
+  readonly message?: Message;
+}
 /**
  * Error type for structured error messages in {@link withDefault} default value callbacks.
  * Unlike regular errors that only support string messages, this error type accepts
@@ -319,9 +339,29 @@ declare class WithDefaultError extends Error {
  *                     doesn't match or consume input. Can be a value of type
  *                     {@link TDefault} or a function that returns such a value.
  * @returns A {@link Parser} that produces either the result of the wrapped parser
- *          or the default value if the wrapped parser fails to match (union type {@link TValue} | {@link TDefault}).
+ *          or the default value if the wrapped parser fails to match
+ *          (union type {@link TValue} | {@link TDefault}).
  */
 declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
+/**
+ * Creates a parser that makes another parser use a default value when it fails
+ * to match or consume input. This is similar to {@link optional}, but instead
+ * of returning `undefined` when the wrapped parser doesn't match, it returns
+ * a specified default value.
+ * @template TValue The type of the value returned by the wrapped parser.
+ * @template TState The type of the state used by the wrapped parser.
+ * @template TDefault The type of the default value.
+ * @param parser The {@link Parser} to wrap with default behavior.
+ * @param defaultValue The default value to return when the wrapped parser
+ *                     doesn't match or consume input. Can be a value of type
+ *                     {@link TDefault} or a function that returns such a value.
+ * @param options Optional configuration including custom help display message.
+ * @returns A {@link Parser} that produces either the result of the wrapped parser
+ *          or the default value if the wrapped parser fails to match
+ *          (union type {@link TValue} | {@link TDefault}).
+ * @since 0.5.0
+ */
+declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving
@@ -1461,4 +1501,4 @@ declare function group<TValue, TState>(label: string, parser: Parser<TValue, TSt
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.d.ts

@@ -276,6 +276,26 @@ declare function argument<T>(valueParser: ValueParser<T>, options?: ArgumentOpti
  *          or `undefined` if the wrapped parser fails to match.
  */
 declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parser<TValue | undefined, [TState] | undefined>;
+/**
+ * Options for the {@link withDefault} parser.
+ */
+interface WithDefaultOptions {
+  /**
+   * Custom message to display in help output instead of the formatted default value.
+   * This allows showing descriptive text like "SERVICE_URL environment variable"
+   * instead of the actual default value.
+   *
+   * @example
+   * ```typescript
+   * withDefault(
+   *   option("--url", url()),
+   *   process.env["SERVICE_URL"],
+   *   { message: message`${envVar("SERVICE_URL")} environment variable` }
+   * )
+   * ```
+   */
+  readonly message?: Message;
+}
 /**
  * Error type for structured error messages in {@link withDefault} default value callbacks.
  * Unlike regular errors that only support string messages, this error type accepts
@@ -319,9 +339,29 @@ declare class WithDefaultError extends Error {
  *                     doesn't match or consume input. Can be a value of type
  *                     {@link TDefault} or a function that returns such a value.
  * @returns A {@link Parser} that produces either the result of the wrapped parser
- *          or the default value if the wrapped parser fails to match (union type {@link TValue} | {@link TDefault}).
+ *          or the default value if the wrapped parser fails to match
+ *          (union type {@link TValue} | {@link TDefault}).
  */
 declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<TValue | TDefault, [TState] | undefined>;
+/**
+ * Creates a parser that makes another parser use a default value when it fails
+ * to match or consume input. This is similar to {@link optional}, but instead
+ * of returning `undefined` when the wrapped parser doesn't match, it returns
+ * a specified default value.
+ * @template TValue The type of the value returned by the wrapped parser.
+ * @template TState The type of the state used by the wrapped parser.
+ * @template TDefault The type of the default value.
+ * @param parser The {@link Parser} to wrap with default behavior.
+ * @param defaultValue The default value to return when the wrapped parser
+ *                     doesn't match or consume input. Can be a value of type
+ *                     {@link TDefault} or a function that returns such a value.
+ * @param options Optional configuration including custom help display message.
+ * @returns A {@link Parser} that produces either the result of the wrapped parser
+ *          or the default value if the wrapped parser fails to match
+ *          (union type {@link TValue} | {@link TDefault}).
+ * @since 0.5.0
+ */
+declare function withDefault<TValue, TState, TDefault = TValue>(parser: Parser<TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving
@@ -1461,4 +1501,4 @@ declare function group<TValue, TState>(label: string, parser: Parser<TValue, TSt
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.js

@@ -209,7 +209,7 @@ function option(...args) {
 					metavar: valueParser?.metavar
 				},
 				description: options.description,
-				default: defaultValue != null && valueParser != null ? valueParser.format(defaultValue) : void 0
+				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0
 			}];
 			return {
 				fragments,
@@ -458,7 +458,7 @@ function argument(valueParser, options = {}) {
 				type: "entry",
 				term,
 				description: options.description,
-				default: defaultValue == null ? void 0 : valueParser.format(defaultValue)
+				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`
 			}];
 			return {
 				fragments,
@@ -556,22 +556,7 @@ var WithDefaultError = class extends Error {
 		this.name = "WithDefaultError";
 	}
 };
-/**
-* Creates a parser that makes another parser use a default value when it fails
-* to match or consume input. This is similar to {@link optional}, but instead
-* of returning `undefined` when the wrapped parser doesn't match, it returns
-* a specified default value.
-* @template TValue The type of the value returned by the wrapped parser.
-* @template TState The type of the state used by the wrapped parser.
-* @template TDefault The type of the default value.
-* @param parser The {@link Parser} to wrap with default behavior.
-* @param defaultValue The default value to return when the wrapped parser
-*                     doesn't match or consume input. Can be a value of type
-*                     {@link TDefault} or a function that returns such a value.
-* @returns A {@link Parser} that produces either the result of the wrapped parser
-*          or the default value if the wrapped parser fails to match (union type {@link TValue} | {@link TDefault}).
-*/
-function withDefault(parser, defaultValue) {
+function withDefault(parser, defaultValue, options) {
 	return {
 		$valueType: [],
 		$stateType: [],
@@ -616,7 +601,22 @@ function withDefault(parser, defaultValue) {
 				kind: "available",
 				state: state.state[0]
 			};
-			return parser.getDocFragments(innerState, upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue);
+			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			const fragments = parser.getDocFragments(innerState, actualDefaultValue);
+			if (options?.message) {
+				const modifiedFragments = fragments.fragments.map((fragment) => {
+					if (fragment.type === "entry") return {
+						...fragment,
+						default: options.message
+					};
+					return fragment;
+				});
+				return {
+					...fragments,
+					fragments: modifiedFragments
+				};
+			}
+			return fragments;
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.5.0-dev.64+84de5850",
+  "version": "0.5.0-dev.65+6fcdf2be",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",