@optique/core 0.10.0-dev.327 → 0.10.0-dev.329

package/dist/doc.cjs

@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null) {
-		output += "Usage: ";
+		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
+		output += usageLabel;
 		output += indentLines(require_usage.formatUsage(programName, page.usage, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
-		if (section.title != null) output += `${section.title}:\n`;
+		if (section.title != null) {
+			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			output += sectionLabel;
+		}
 		for (const entry of section.entries) {
 			const term = require_usage.formatUsageTerm(entry.term, {
 				colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
+	if (page.examples != null) {
+		output += "\n";
+		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		output += examplesLabel;
+		const examplesContent = require_message.formatMessage(page.examples, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(examplesContent, 2);
+		output += "\n";
+	}
+	if (page.author != null) {
+		output += "\n";
+		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		output += authorLabel;
+		const authorContent = require_message.formatMessage(page.author, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(authorContent, 2);
+		output += "\n";
+	}
+	if (page.bugs != null) {
+		output += "\n";
+		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		output += bugsLabel;
+		const bugsContent = require_message.formatMessage(page.bugs, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(bugsContent, 2);
+		output += "\n";
+	}
 	if (page.footer != null) {
 		output += "\n";
 		output += require_message.formatMessage(page.footer, {

package/dist/doc.d.cts

@@ -43,6 +43,21 @@ interface DocPage {
   readonly usage?: Usage;
   readonly description?: Message;
   readonly sections: readonly DocSection[];
+  /**
+   * Usage examples for the program.
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   readonly footer?: Message;
 }
 /**

package/dist/doc.d.ts

@@ -43,6 +43,21 @@ interface DocPage {
   readonly usage?: Usage;
   readonly description?: Message;
   readonly sections: readonly DocSection[];
+  /**
+   * Usage examples for the program.
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   readonly footer?: Message;
 }
 /**

package/dist/doc.js

@@ -46,7 +46,8 @@ function formatDocPage(programName, page, options = {}) {
 		output += "\n";
 	}
 	if (page.usage != null) {
-		output += "Usage: ";
+		const usageLabel = options.colors ? "\x1B[1;2mUsage:\x1B[0m " : "Usage: ";
+		output += usageLabel;
 		output += indentLines(formatUsage(programName, page.usage, {
 			colors: options.colors,
 			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 7,
@@ -67,7 +68,10 @@ function formatDocPage(programName, page, options = {}) {
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
-		if (section.title != null) output += `${section.title}:\n`;
+		if (section.title != null) {
+			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
+			output += sectionLabel;
+		}
 		for (const entry of section.entries) {
 			const term = formatUsageTerm(entry.term, {
 				colors: options.colors,
@@ -92,6 +96,42 @@ function formatDocPage(programName, page, options = {}) {
 			output += `${" ".repeat(termIndent)}${ansiAwareRightPad(term, termWidth)}  ${description === "" ? "" : indentLines(description, termIndent + termWidth + 2)}\n`;
 		}
 	}
+	if (page.examples != null) {
+		output += "\n";
+		const examplesLabel = options.colors ? "\x1B[1;2mExamples:\x1B[0m\n" : "Examples:\n";
+		output += examplesLabel;
+		const examplesContent = formatMessage(page.examples, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(examplesContent, 2);
+		output += "\n";
+	}
+	if (page.author != null) {
+		output += "\n";
+		const authorLabel = options.colors ? "\x1B[1;2mAuthor:\x1B[0m\n" : "Author:\n";
+		output += authorLabel;
+		const authorContent = formatMessage(page.author, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(authorContent, 2);
+		output += "\n";
+	}
+	if (page.bugs != null) {
+		output += "\n";
+		const bugsLabel = options.colors ? "\x1B[1;2mBugs:\x1B[0m\n" : "Bugs:\n";
+		output += bugsLabel;
+		const bugsContent = formatMessage(page.bugs, {
+			colors: options.colors,
+			maxWidth: options.maxWidth == null ? void 0 : options.maxWidth - 2,
+			quotes: !options.colors
+		});
+		output += "  " + indentLines(bugsContent, 2);
+		output += "\n";
+	}
 	if (page.footer != null) {
 		output += "\n";
 		output += formatMessage(page.footer, {

package/dist/facade.cjs

@@ -419,6 +419,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			...options,
 			brief: options.brief ?? program.metadata.brief,
 			description: options.description ?? program.metadata.description,
+			examples: options.examples ?? program.metadata.examples,
+			author: options.author ?? program.metadata.author,
+			bugs: options.bugs ?? program.metadata.bugs,
 			footer: options.footer ?? program.metadata.footer
 		};
 	} else {
@@ -429,7 +432,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
@@ -530,6 +533,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							...doc,
 							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
 							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
+							author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
+							bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
 							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
 						};
 						stdout(require_doc.formatDocPage(programName, augmentedDoc, {
@@ -557,6 +563,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
+							examples: examples ?? doc.examples,
+							author: author ?? doc.author,
+							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
 						};
 						stderr(require_doc.formatDocPage(programName, augmentedDoc, {

package/dist/facade.d.cts

@@ -178,6 +178,24 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -214,7 +232,7 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
- * @since 0.11.0 Added support for {@link Program} objects.
+ * @since 0.10.0 Added support for {@link Program} objects.
  */
 declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
 declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;

package/dist/facade.d.ts

@@ -178,6 +178,24 @@ interface RunOptions<THelp, TError> {
    * @since 0.4.0
    */
   readonly description?: Message;
+  /**
+   * Usage examples for the program.
+   *
+   * @since 0.10.0
+   */
+  readonly examples?: Message;
+  /**
+   * Author information.
+   *
+   * @since 0.10.0
+   */
+  readonly author?: Message;
+  /**
+   * Information about where to report bugs.
+   *
+   * @since 0.10.0
+   */
+  readonly bugs?: Message;
   /**
    * Footer text shown at the bottom of help text.
    *
@@ -214,7 +232,7 @@ interface RunOptions<THelp, TError> {
  *          callbacks.
  * @throws {RunParserError} When parsing fails and no `onError` callback is
  *          provided.
- * @since 0.11.0 Added support for {@link Program} objects.
+ * @since 0.10.0 Added support for {@link Program} objects.
  */
 declare function runParser<T, THelp = void, TError = never>(program: Program<"sync", T>, args: readonly string[], options?: RunOptions<THelp, TError>): T;
 declare function runParser<T, THelp = void, TError = never>(program: Program<"async", T>, args: readonly string[], options?: RunOptions<THelp, TError>): Promise<T>;

package/dist/facade.js

@@ -419,6 +419,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 			...options,
 			brief: options.brief ?? program.metadata.brief,
 			description: options.description ?? program.metadata.description,
+			examples: options.examples ?? program.metadata.examples,
+			author: options.author ?? program.metadata.author,
+			bugs: options.bugs ?? program.metadata.bugs,
 			footer: options.footer ?? program.metadata.footer
 		};
 	} else {
@@ -429,7 +432,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	}
 	const { colors, maxWidth, showDefault, aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
-	}, stderr = console.error, stdout = console.log, brief, description, footer } = options;
+	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const helpMode = options.help?.mode ?? "option";
 	const onHelp = options.help?.onShow ?? (() => ({}));
 	const versionMode = options.version?.mode ?? "option";
@@ -530,6 +533,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							...doc,
 							brief: !isMetaCommandHelp ? brief ?? doc.brief : doc.brief,
 							description: !isMetaCommandHelp ? description ?? doc.description : doc.description,
+							examples: !isMetaCommandHelp ? examples ?? doc.examples : doc.examples,
+							author: !isMetaCommandHelp ? author ?? doc.author : doc.author,
+							bugs: !isMetaCommandHelp ? bugs ?? doc.bugs : doc.bugs,
 							footer: !isMetaCommandHelp ? footer ?? doc.footer : doc.footer
 						};
 						stdout(formatDocPage(programName, augmentedDoc, {
@@ -557,6 +563,9 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 							...doc,
 							brief: brief ?? doc.brief,
 							description: description ?? doc.description,
+							examples: examples ?? doc.examples,
+							author: author ?? doc.author,
+							bugs: bugs ?? doc.bugs,
 							footer: footer ?? doc.footer
 						};
 						stderr(formatDocPage(programName, augmentedDoc, {

package/dist/index.cjs

@@ -65,6 +65,7 @@ exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isPendingDependencySourceState = require_dependency.isPendingDependencySourceState;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.isWrappedDependencySource = require_dependency.isWrappedDependencySource;
+exports.link = require_message.link;
 exports.locale = require_valueparser.locale;
 exports.longestMatch = require_constructs.longestMatch;
 exports.map = require_modifiers.map;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
+import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, 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 { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
@@ -10,4 +10,4 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.cjs";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, 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 { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
@@ -10,4 +10,4 @@ import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOpti
 import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, ModeValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunOptions, RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
-export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, FloatOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, ResolvedDependency, Result, RunOptions, RunParserError, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
+import { commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
@@ -11,4 +11,4 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, integer, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isNonEmptyString, isPendingDependencySourceState, isValueParser, isWrappedDependencySource, link, locale, longestMatch, map, merge, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, pwsh, runParser, runParserAsync, runParserSync, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/message.cjs

@@ -140,6 +140,43 @@ function commandLine(commandLine$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for a URL.
+* @param url The URL, which can be a URL object or a string that can be parsed
+*            as a URL. For example, `"https://example.com"` or
+*            `new URL("https://example.com")`.
+* @returns A {@link MessageTerm} representing the URL.
+* @throws {RangeError} If the URL string cannot be parsed.
+* @since 0.10.0
+*/
+function url(url$1) {
+	let urlObj;
+	if (typeof url$1 === "string") {
+		if (!URL.canParse(url$1)) throw new RangeError(`Invalid URL: ${url$1}.`);
+		urlObj = new URL(url$1);
+	} else urlObj = url$1;
+	return {
+		type: "url",
+		url: urlObj
+	};
+}
+/**
+* Creates a {@link MessageTerm} for a URL (alias for {@link url}).
+*
+* This is an alias for the {@link url} function, provided for convenience
+* when you want to avoid potential naming conflicts with the `url()` value
+* parser from `@optique/core/valueparser`.
+*
+* @param href The URL, which can be a URL object or a string that can be parsed
+*             as a URL. For example, `"https://example.com"` or
+*             `new URL("https://example.com")`.
+* @returns A {@link MessageTerm} representing the URL.
+* @throws {RangeError} If the URL string cannot be parsed.
+* @since 0.10.0
+*/
+function link(href) {
+	return url(href);
+}
+/**
 * Creates a {@link Message} for a formatted list of values using the
 * `Intl.ListFormat` API.  This is useful for displaying choice lists
 * in error messages with proper locale-aware formatting.
@@ -295,6 +332,19 @@ function formatMessage(msg, options = {}) {
 				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
 				width: cmd.length
 			};
+		} else if (term.type === "url") {
+			const urlString = term.url.href;
+			const displayText = useQuotes ? `<${urlString}>` : urlString;
+			if (useColors) {
+				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+				yield {
+					text: hyperlink,
+					width: displayText.length
+				};
+			} else yield {
+				text: displayText,
+				width: displayText.length
+			};
 		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 	}
 	let output = "";
@@ -319,11 +369,13 @@ function formatMessage(msg, options = {}) {
 exports.commandLine = commandLine;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;
+exports.link = link;
 exports.message = message;
 exports.metavar = metavar;
 exports.optionName = optionName;
 exports.optionNames = optionNames;
 exports.text = text;
+exports.url = url;
 exports.value = value;
 exports.valueSet = valueSet;
 exports.values = values;

package/dist/message.d.cts

@@ -122,6 +122,19 @@ type MessageTerm =
    * For example, `"myapp completion bash > myapp-completion.bash"`.
    */
   readonly commandLine: string;
+}
+/**
+ * A URL term in the message, which represents a clickable hyperlink.
+ * @since 0.10.0
+ */ | {
+  /**
+   * The type of the term, which is `"url"` for a URL.
+   */
+  readonly type: "url";
+  /**
+   * The URL object representing the hyperlink.
+   */
+  readonly url: URL;
 };
 /**
  * Type representing a message that can include styled/colored values.
@@ -210,6 +223,31 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for a URL.
+ * @param url The URL, which can be a URL object or a string that can be parsed
+ *            as a URL. For example, `"https://example.com"` or
+ *            `new URL("https://example.com")`.
+ * @returns A {@link MessageTerm} representing the URL.
+ * @throws {RangeError} If the URL string cannot be parsed.
+ * @since 0.10.0
+ */
+declare function url(url: string | URL): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for a URL (alias for {@link url}).
+ *
+ * This is an alias for the {@link url} function, provided for convenience
+ * when you want to avoid potential naming conflicts with the `url()` value
+ * parser from `@optique/core/valueparser`.
+ *
+ * @param href The URL, which can be a URL object or a string that can be parsed
+ *             as a URL. For example, `"https://example.com"` or
+ *             `new URL("https://example.com")`.
+ * @returns A {@link MessageTerm} representing the URL.
+ * @throws {RangeError} If the URL string cannot be parsed.
+ * @since 0.10.0
+ */
+declare function link(href: string | URL): MessageTerm;
 /**
  * Options for the {@link valueSet} function.
  * @since 0.9.0
@@ -323,4 +361,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -122,6 +122,19 @@ type MessageTerm =
    * For example, `"myapp completion bash > myapp-completion.bash"`.
    */
   readonly commandLine: string;
+}
+/**
+ * A URL term in the message, which represents a clickable hyperlink.
+ * @since 0.10.0
+ */ | {
+  /**
+   * The type of the term, which is `"url"` for a URL.
+   */
+  readonly type: "url";
+  /**
+   * The URL object representing the hyperlink.
+   */
+  readonly url: URL;
 };
 /**
  * Type representing a message that can include styled/colored values.
@@ -210,6 +223,31 @@ declare function envVar(envVar: string): MessageTerm;
  * @since 0.6.0
  */
 declare function commandLine(commandLine: string): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for a URL.
+ * @param url The URL, which can be a URL object or a string that can be parsed
+ *            as a URL. For example, `"https://example.com"` or
+ *            `new URL("https://example.com")`.
+ * @returns A {@link MessageTerm} representing the URL.
+ * @throws {RangeError} If the URL string cannot be parsed.
+ * @since 0.10.0
+ */
+declare function url(url: string | URL): MessageTerm;
+/**
+ * Creates a {@link MessageTerm} for a URL (alias for {@link url}).
+ *
+ * This is an alias for the {@link url} function, provided for convenience
+ * when you want to avoid potential naming conflicts with the `url()` value
+ * parser from `@optique/core/valueparser`.
+ *
+ * @param href The URL, which can be a URL object or a string that can be parsed
+ *             as a URL. For example, `"https://example.com"` or
+ *             `new URL("https://example.com")`.
+ * @returns A {@link MessageTerm} representing the URL.
+ * @throws {RangeError} If the URL string cannot be parsed.
+ * @since 0.10.0
+ */
+declare function link(href: string | URL): MessageTerm;
 /**
  * Options for the {@link valueSet} function.
  * @since 0.9.0
@@ -323,4 +361,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.js

@@ -139,6 +139,43 @@ function commandLine(commandLine$1) {
 	};
 }
 /**
+* Creates a {@link MessageTerm} for a URL.
+* @param url The URL, which can be a URL object or a string that can be parsed
+*            as a URL. For example, `"https://example.com"` or
+*            `new URL("https://example.com")`.
+* @returns A {@link MessageTerm} representing the URL.
+* @throws {RangeError} If the URL string cannot be parsed.
+* @since 0.10.0
+*/
+function url(url$1) {
+	let urlObj;
+	if (typeof url$1 === "string") {
+		if (!URL.canParse(url$1)) throw new RangeError(`Invalid URL: ${url$1}.`);
+		urlObj = new URL(url$1);
+	} else urlObj = url$1;
+	return {
+		type: "url",
+		url: urlObj
+	};
+}
+/**
+* Creates a {@link MessageTerm} for a URL (alias for {@link url}).
+*
+* This is an alias for the {@link url} function, provided for convenience
+* when you want to avoid potential naming conflicts with the `url()` value
+* parser from `@optique/core/valueparser`.
+*
+* @param href The URL, which can be a URL object or a string that can be parsed
+*             as a URL. For example, `"https://example.com"` or
+*             `new URL("https://example.com")`.
+* @returns A {@link MessageTerm} representing the URL.
+* @throws {RangeError} If the URL string cannot be parsed.
+* @since 0.10.0
+*/
+function link(href) {
+	return url(href);
+}
+/**
 * Creates a {@link Message} for a formatted list of values using the
 * `Intl.ListFormat` API.  This is useful for displaying choice lists
 * in error messages with proper locale-aware formatting.
@@ -294,6 +331,19 @@ function formatMessage(msg, options = {}) {
 				text: useColors ? `\x1b[36m${cmd}${resetSequence}` : cmd,
 				width: cmd.length
 			};
+		} else if (term.type === "url") {
+			const urlString = term.url.href;
+			const displayText = useQuotes ? `<${urlString}>` : urlString;
+			if (useColors) {
+				const hyperlink = `\x1b]8;;${urlString}\x1b\\${displayText}\x1b]8;;\x1b\\${resetSuffix}`;
+				yield {
+					text: hyperlink,
+					width: displayText.length
+				};
+			} else yield {
+				text: displayText,
+				width: displayText.length
+			};
 		} else throw new TypeError(`Invalid MessageTerm type: ${term["type"]}.`);
 	}
 	let output = "";
@@ -315,4 +365,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, valueSet, values };
+export { commandLine, envVar, formatMessage, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/program.d.cts

@@ -6,7 +6,7 @@ import { Mode, Parser } from "./parser.cjs";
 /**
  * Metadata for a CLI program.
  *
- * @since 0.11.0
+ * @since 0.10.0
  */
 interface ProgramMetadata {
   /**

package/dist/program.d.ts

@@ -6,7 +6,7 @@ import { Mode, Parser } from "./parser.js";
 /**
  * Metadata for a CLI program.
  *
- * @since 0.11.0
+ * @since 0.10.0
  */
 interface ProgramMetadata {
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.327+76d21ea0",
+  "version": "0.10.0-dev.329+96b4ad62",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",