@optique/core 1.0.0-dev.1523 → 1.0.0-dev.1533

package/dist/constructs.cjs

@@ -2591,7 +2591,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			result.push(optionWithoutMetavar);
 			result.push({
 				type: "literal",
-				value: literalValue
+				value: literalValue,
+				optionValue: true
 			});
 		} else if (term.type === "optional") result.push({
 			...term,

package/dist/constructs.js

@@ -2591,7 +2591,8 @@ function conditional(discriminator, branches, defaultBranch, options) {
 			result.push(optionWithoutMetavar);
 			result.push({
 				type: "literal",
-				value: literalValue
+				value: literalValue,
+				optionValue: true
 			});
 		} else if (term.type === "optional") result.push({
 			...term,

package/dist/facade.cjs

@@ -622,6 +622,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	require_validate.validateMetaNameCollisions({
 		leadingOptions: require_usage.extractLeadingOptionNames(parser.usage, true),
 		leadingCommands: require_usage.extractLeadingCommandNames(parser.usage, true),
+		leadingLiterals: require_usage.extractLeadingLiteralValues(parser.usage),
 		allOptions: require_usage.extractOptionNames(parser.usage, true),
 		allCommands: require_usage.extractCommandNames(parser.usage, true),
 		allLiterals: require_usage.extractLiteralValues(parser.usage)

package/dist/facade.js

@@ -3,7 +3,7 @@ import { commandLine, formatMessage, lineBreak, message, optionName, text, value
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { validateCommandNames, validateMetaNameCollisions, validateOptionNames } from "./validate.js";
-import { extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
+import { extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -622,6 +622,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 	validateMetaNameCollisions({
 		leadingOptions: extractLeadingOptionNames(parser.usage, true),
 		leadingCommands: extractLeadingCommandNames(parser.usage, true),
+		leadingLiterals: extractLeadingLiteralValues(parser.usage),
 		allOptions: extractOptionNames(parser.usage, true),
 		allCommands: extractCommandNames(parser.usage, true),
 		allLiterals: extractLiteralValues(parser.usage)

package/dist/index.cjs

@@ -54,6 +54,7 @@ exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;
 exports.extractCommandNames = require_usage.extractCommandNames;
 exports.extractLeadingCommandNames = require_usage.extractLeadingCommandNames;
+exports.extractLeadingLiteralValues = require_usage.extractLeadingLiteralValues;
 exports.extractLeadingOptionNames = require_usage.extractLeadingOptionNames;
 exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

@@ -2,7 +2,7 @@ import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, 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 { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/parser.cjs

@@ -299,14 +299,20 @@ function findCommandInExclusive(term, commandName) {
 * in a Promise).
 *
 * @param parser The sync parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageSync(parser, args = [], options) {
-	return getDocPageSyncImpl(parser, args, options);
+function getDocPageSync(parser, argsOrOptions, options) {
+	if (Array.isArray(argsOrOptions)) return getDocPageSyncImpl(parser, argsOrOptions, options);
+	return getDocPageSyncImpl(parser, [], argsOrOptions ?? options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -316,19 +322,28 @@ function getDocPageSync(parser, args = [], options) {
 * async value parsers.
 *
 * @param parser The parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageAsync(parser, args = [], options) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPageAsync(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, opts));
+	return getDocPageAsyncImpl(parser, args, opts);
 }
-function getDocPage(parser, args = [], options) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPage(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, opts);
+	return getDocPageAsyncImpl(parser, args, opts);
 }
 /**
 * Internal sync implementation of getDocPage.

package/dist/parser.d.cts

@@ -511,13 +511,18 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * in a Promise).
  *
  * @param parser The sync parser to generate documentation for.
- * @param args Optional array of command-line arguments for context.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -526,13 +531,18 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  * async value parsers.
  *
  * @param parser The parser to generate documentation for.
- * @param args Optional array of command-line arguments for context.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -548,10 +558,12 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * For async parsers, returns a Promise of the documentation page.
  *
  * @param parser The parser to generate documentation for
- * @param args Optional array of command-line arguments that have been parsed
- *             so far. Defaults to an empty array. This is used to determine
- *             the current parsing context and generate contextual documentation.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments that have been
+ *        parsed so far, or a {@link ParseOptions} object for annotations.
+ *        When a `ParseOptions` is passed here, the `options` parameter is
+ *        ignored.  Defaults to an empty array when omitted.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -571,9 +583,11 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * ```
  * @since 0.9.0 Updated to support async parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.d.ts

@@ -511,13 +511,18 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * in a Promise).
  *
  * @param parser The sync parser to generate documentation for.
- * @param args Optional array of command-line arguments for context.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -526,13 +531,18 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  * async value parsers.
  *
  * @param parser The parser to generate documentation for.
- * @param args Optional array of command-line arguments for context.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -548,10 +558,12 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * For async parsers, returns a Promise of the documentation page.
  *
  * @param parser The parser to generate documentation for
- * @param args Optional array of command-line arguments that have been parsed
- *             so far. Defaults to an empty array. This is used to determine
- *             the current parsing context and generate contextual documentation.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments that have been
+ *        parsed so far, or a {@link ParseOptions} object for annotations.
+ *        When a `ParseOptions` is passed here, the `options` parameter is
+ *        ignored.  Defaults to an empty array when omitted.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -571,9 +583,11 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * ```
  * @since 0.9.0 Updated to support async parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };

package/dist/parser.js

@@ -299,14 +299,20 @@ function findCommandInExclusive(term, commandName) {
 * in a Promise).
 *
 * @param parser The sync parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageSync(parser, args = [], options) {
-	return getDocPageSyncImpl(parser, args, options);
+function getDocPageSync(parser, argsOrOptions, options) {
+	if (Array.isArray(argsOrOptions)) return getDocPageSyncImpl(parser, argsOrOptions, options);
+	return getDocPageSyncImpl(parser, [], argsOrOptions ?? options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -316,19 +322,28 @@ function getDocPageSync(parser, args = [], options) {
 * async value parsers.
 *
 * @param parser The parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageAsync(parser, args = [], options) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPageAsync(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, opts));
+	return getDocPageAsyncImpl(parser, args, opts);
 }
-function getDocPage(parser, args = [], options) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPage(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, opts);
+	return getDocPageAsyncImpl(parser, args, opts);
 }
 /**
 * Internal sync implementation of getDocPage.

package/dist/usage.cjs

@@ -121,10 +121,8 @@ function extractCommandNames(usage, includeHidden) {
 * appearing before commands due to priority sorting) and false negatives
 * (e.g., options after commands that are actually parallel peers).
 * The proper fix is to use `Parser.leadingNames` instead of usage-tree
-* analysis.  This also cannot detect `conditional(argument(...))`
-* discriminator values, which never appear in the usage tree.
-* See https://github.com/dahlia/optique/issues/734 and
-* https://github.com/dahlia/optique/issues/735
+* analysis.
+* See https://github.com/dahlia/optique/issues/735
 *
 * @param usage The usage description to extract leading option names from.
 * @param includeHidden Whether to include fully hidden options
@@ -172,10 +170,9 @@ function extractLeadingOptionNames(usage, includeHidden) {
 * `exclusive` containers, since they represent alternatives or optional
 * wrappers at the same token position.
 *
-* Known limitation: this function has the same usage-tree ordering and
-* `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
-* See https://github.com/dahlia/optique/issues/734 and
-* https://github.com/dahlia/optique/issues/735
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
 *
 * @param usage The usage description to extract leading command names from.
 * @param includeHidden Whether to include fully hidden commands
@@ -212,27 +209,86 @@ function extractLeadingCommandNames(usage, includeHidden) {
 	return names;
 }
 /**
+* Extracts literal values that could match as the first positional token.
+*
+* Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms in that array are
+* scoped under that positional token.  It still recurses into `optional`,
+* `multiple`, and `exclusive` containers.
+*
+* Literals tagged with `optionValue: true` (produced by
+* `appendLiteralToUsage()` when rewriting option metavars for
+* `conditional()` discriminators) are skipped, because they represent
+* option values rather than standalone positional tokens.
+*
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading literal values from.
+* @returns A set of literal values that could match at the first token
+*   position.
+* @since 1.0.0
+*/
+function extractLeadingLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "literal":
+				if (term.optionValue) break;
+				values.add(term.value);
+				return;
+			case "command":
+			case "argument": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms, true)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms, true)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return values;
+}
+/**
 * Checks whether every branch of an exclusive term must consume a positional
 * token.  When true, terms after the exclusive are at position N+1 and should
 * not be considered "leading".
+*
+* @param skipOptionValueLiterals When `true`, literals tagged with
+*   `optionValue` are treated as non-positional.  Only
+*   `extractLeadingLiteralValues()` passes `true`; the option/command
+*   extractors use the default (`false`) so that option+value pairs
+*   still act as positional gates.
 */
-function exclusiveConsumesToken(branches) {
+function exclusiveConsumesToken(branches, skipOptionValueLiterals = false) {
 	if (branches.length === 0) return false;
-	return branches.every((branch) => branchConsumesToken(branch));
+	return branches.every((branch) => branchConsumesToken(branch, skipOptionValueLiterals));
 }
-function branchConsumesToken(terms) {
+function branchConsumesToken(terms, skipOptionValueLiterals = false) {
 	if (!terms || !Array.isArray(terms)) return false;
 	for (const term of terms) switch (term.type) {
 		case "command":
-		case "argument":
-		case "literal": return true;
+		case "argument": return true;
+		case "literal":
+			if (skipOptionValueLiterals && term.optionValue) break;
+			return true;
 		case "option": break;
 		case "optional": break;
 		case "multiple":
-			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			if (term.min > 0 && branchConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		case "exclusive":
-			if (exclusiveConsumesToken(term.terms)) return true;
+			if (exclusiveConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		default: break;
 	}
@@ -714,6 +770,7 @@ exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
 exports.extractLeadingCommandNames = extractLeadingCommandNames;
+exports.extractLeadingLiteralValues = extractLeadingLiteralValues;
 exports.extractLeadingOptionNames = extractLeadingOptionNames;
 exports.extractLiteralValues = extractLiteralValues;
 exports.extractOptionNames = extractOptionNames;

package/dist/usage.d.cts

@@ -178,6 +178,18 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+  /**
+   * When `true`, this literal was derived from an option's metavar by
+   * `appendLiteralToUsage()` in `conditional()` and represents an option
+   * value, not a standalone positional token.
+   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
+   * mode of `branchConsumesToken()` use this to distinguish option values
+   * from real positional literals.  {@link extractLeadingOptionNames} and
+   * {@link extractLeadingCommandNames} intentionally still treat these
+   * literals as positional gates.
+   * @since 1.0.0
+   */
+  readonly optionValue?: boolean;
 }
 /**
  * A pass-through term, which represents unrecognized options that are
@@ -276,10 +288,8 @@ declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set
  * appearing before commands due to priority sorting) and false negatives
  * (e.g., options after commands that are actually parallel peers).
  * The proper fix is to use `Parser.leadingNames` instead of usage-tree
- * analysis.  This also cannot detect `conditional(argument(...))`
- * discriminator values, which never appear in the usage tree.
- * See https://github.com/dahlia/optique/issues/734 and
- * https://github.com/dahlia/optique/issues/735
+ * analysis.
+ * See https://github.com/dahlia/optique/issues/735
  *
  * @param usage The usage description to extract leading option names from.
  * @param includeHidden Whether to include fully hidden options
@@ -299,10 +309,9 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * `exclusive` containers, since they represent alternatives or optional
  * wrappers at the same token position.
  *
- * Known limitation: this function has the same usage-tree ordering and
- * `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
- * See https://github.com/dahlia/optique/issues/734 and
- * https://github.com/dahlia/optique/issues/735
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
  *
  * @param usage The usage description to extract leading command names from.
  * @param includeHidden Whether to include fully hidden commands
@@ -311,6 +320,30 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * @since 1.0.0
  */
 declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts literal values that could match as the first positional token.
+ *
+ * Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms in that array are
+ * scoped under that positional token.  It still recurses into `optional`,
+ * `multiple`, and `exclusive` containers.
+ *
+ * Literals tagged with `optionValue: true` (produced by
+ * `appendLiteralToUsage()` when rewriting option metavars for
+ * `conditional()` discriminators) are skipped, because they represent
+ * option values rather than standalone positional tokens.
+ *
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading literal values from.
+ * @returns A set of literal values that could match at the first token
+ *   position.
+ * @since 1.0.0
+ */
+declare function extractLeadingLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all literal values from a usage description.
  *
@@ -487,4 +520,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -178,6 +178,18 @@ type UsageTerm =
    * The literal value that must be provided exactly as written.
    */
   readonly value: string;
+  /**
+   * When `true`, this literal was derived from an option's metavar by
+   * `appendLiteralToUsage()` in `conditional()` and represents an option
+   * value, not a standalone positional token.
+   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
+   * mode of `branchConsumesToken()` use this to distinguish option values
+   * from real positional literals.  {@link extractLeadingOptionNames} and
+   * {@link extractLeadingCommandNames} intentionally still treat these
+   * literals as positional gates.
+   * @since 1.0.0
+   */
+  readonly optionValue?: boolean;
 }
 /**
  * A pass-through term, which represents unrecognized options that are
@@ -276,10 +288,8 @@ declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set
  * appearing before commands due to priority sorting) and false negatives
  * (e.g., options after commands that are actually parallel peers).
  * The proper fix is to use `Parser.leadingNames` instead of usage-tree
- * analysis.  This also cannot detect `conditional(argument(...))`
- * discriminator values, which never appear in the usage tree.
- * See https://github.com/dahlia/optique/issues/734 and
- * https://github.com/dahlia/optique/issues/735
+ * analysis.
+ * See https://github.com/dahlia/optique/issues/735
  *
  * @param usage The usage description to extract leading option names from.
  * @param includeHidden Whether to include fully hidden options
@@ -299,10 +309,9 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * `exclusive` containers, since they represent alternatives or optional
  * wrappers at the same token position.
  *
- * Known limitation: this function has the same usage-tree ordering and
- * `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
- * See https://github.com/dahlia/optique/issues/734 and
- * https://github.com/dahlia/optique/issues/735
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
  *
  * @param usage The usage description to extract leading command names from.
  * @param includeHidden Whether to include fully hidden commands
@@ -311,6 +320,30 @@ declare function extractLeadingOptionNames(usage: Usage, includeHidden?: boolean
  * @since 1.0.0
  */
 declare function extractLeadingCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
+/**
+ * Extracts literal values that could match as the first positional token.
+ *
+ * Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
+ * this function stops scanning a terms array after encountering a `command`,
+ * `argument`, or `literal` term, because subsequent terms in that array are
+ * scoped under that positional token.  It still recurses into `optional`,
+ * `multiple`, and `exclusive` containers.
+ *
+ * Literals tagged with `optionValue: true` (produced by
+ * `appendLiteralToUsage()` when rewriting option metavars for
+ * `conditional()` discriminators) are skipped, because they represent
+ * option values rather than standalone positional tokens.
+ *
+ * Known limitation: this function has the same usage-tree ordering caveat
+ * as {@link extractLeadingOptionNames}.
+ * See https://github.com/dahlia/optique/issues/735
+ *
+ * @param usage The usage description to extract leading literal values from.
+ * @returns A set of literal values that could match at the first token
+ *   position.
+ * @since 1.0.0
+ */
+declare function extractLeadingLiteralValues(usage: Usage): Set<string>;
 /**
  * Extracts all literal values from a usage description.
  *
@@ -487,4 +520,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -121,10 +121,8 @@ function extractCommandNames(usage, includeHidden) {
 * appearing before commands due to priority sorting) and false negatives
 * (e.g., options after commands that are actually parallel peers).
 * The proper fix is to use `Parser.leadingNames` instead of usage-tree
-* analysis.  This also cannot detect `conditional(argument(...))`
-* discriminator values, which never appear in the usage tree.
-* See https://github.com/dahlia/optique/issues/734 and
-* https://github.com/dahlia/optique/issues/735
+* analysis.
+* See https://github.com/dahlia/optique/issues/735
 *
 * @param usage The usage description to extract leading option names from.
 * @param includeHidden Whether to include fully hidden options
@@ -172,10 +170,9 @@ function extractLeadingOptionNames(usage, includeHidden) {
 * `exclusive` containers, since they represent alternatives or optional
 * wrappers at the same token position.
 *
-* Known limitation: this function has the same usage-tree ordering and
-* `conditional(argument(...))` caveats as {@link extractLeadingOptionNames}.
-* See https://github.com/dahlia/optique/issues/734 and
-* https://github.com/dahlia/optique/issues/735
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
 *
 * @param usage The usage description to extract leading command names from.
 * @param includeHidden Whether to include fully hidden commands
@@ -212,27 +209,86 @@ function extractLeadingCommandNames(usage, includeHidden) {
 	return names;
 }
 /**
+* Extracts literal values that could match as the first positional token.
+*
+* Unlike {@link extractLiteralValues}, which traverses the entire usage tree,
+* this function stops scanning a terms array after encountering a `command`,
+* `argument`, or `literal` term, because subsequent terms in that array are
+* scoped under that positional token.  It still recurses into `optional`,
+* `multiple`, and `exclusive` containers.
+*
+* Literals tagged with `optionValue: true` (produced by
+* `appendLiteralToUsage()` when rewriting option metavars for
+* `conditional()` discriminators) are skipped, because they represent
+* option values rather than standalone positional tokens.
+*
+* Known limitation: this function has the same usage-tree ordering caveat
+* as {@link extractLeadingOptionNames}.
+* See https://github.com/dahlia/optique/issues/735
+*
+* @param usage The usage description to extract leading literal values from.
+* @returns A set of literal values that could match at the first token
+*   position.
+* @since 1.0.0
+*/
+function extractLeadingLiteralValues(usage) {
+	const values = /* @__PURE__ */ new Set();
+	function collectLeading(terms) {
+		if (!terms || !Array.isArray(terms)) return;
+		for (const term of terms) switch (term.type) {
+			case "literal":
+				if (term.optionValue) break;
+				values.add(term.value);
+				return;
+			case "command":
+			case "argument": return;
+			case "optional":
+				collectLeading(term.terms);
+				break;
+			case "multiple":
+				collectLeading(term.terms);
+				if (term.min > 0 && branchConsumesToken(term.terms, true)) return;
+				break;
+			case "exclusive":
+				for (const branch of term.terms) collectLeading(branch);
+				if (exclusiveConsumesToken(term.terms, true)) return;
+				break;
+			default: break;
+		}
+	}
+	collectLeading(usage);
+	return values;
+}
+/**
 * Checks whether every branch of an exclusive term must consume a positional
 * token.  When true, terms after the exclusive are at position N+1 and should
 * not be considered "leading".
+*
+* @param skipOptionValueLiterals When `true`, literals tagged with
+*   `optionValue` are treated as non-positional.  Only
+*   `extractLeadingLiteralValues()` passes `true`; the option/command
+*   extractors use the default (`false`) so that option+value pairs
+*   still act as positional gates.
 */
-function exclusiveConsumesToken(branches) {
+function exclusiveConsumesToken(branches, skipOptionValueLiterals = false) {
 	if (branches.length === 0) return false;
-	return branches.every((branch) => branchConsumesToken(branch));
+	return branches.every((branch) => branchConsumesToken(branch, skipOptionValueLiterals));
 }
-function branchConsumesToken(terms) {
+function branchConsumesToken(terms, skipOptionValueLiterals = false) {
 	if (!terms || !Array.isArray(terms)) return false;
 	for (const term of terms) switch (term.type) {
 		case "command":
-		case "argument":
-		case "literal": return true;
+		case "argument": return true;
+		case "literal":
+			if (skipOptionValueLiterals && term.optionValue) break;
+			return true;
 		case "option": break;
 		case "optional": break;
 		case "multiple":
-			if (term.min > 0 && branchConsumesToken(term.terms)) return true;
+			if (term.min > 0 && branchConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		case "exclusive":
-			if (exclusiveConsumesToken(term.terms)) return true;
+			if (exclusiveConsumesToken(term.terms, skipOptionValueLiterals)) return true;
 			break;
 		default: break;
 	}
@@ -709,4 +765,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLeadingCommandNames, extractLeadingLiteralValues, extractLeadingOptionNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/validate.cjs

@@ -118,12 +118,13 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 		for (const name of names) {
 			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
 			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
+			if (literalNames.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
 			if (prefixMatch) {
 				const prefix = name + "=";
 				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}

package/dist/validate.js

@@ -117,12 +117,13 @@ function validateMetaNameCollisions(userNames, metaEntries) {
 		for (const name of names) {
 			if (optionNames.has(name)) throw new TypeError(`User-defined option "${name}" conflicts with the built-in ${label}.`);
 			if (commandNames.has(name)) throw new TypeError(`User-defined command "${name}" conflicts with the built-in ${label}.`);
-			if (kind === "option" && userNames.allLiterals.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
+			const literalNames = kind === "command" ? userNames.leadingLiterals : userNames.allLiterals;
+			if (literalNames.has(name)) throw new TypeError(`Literal value "${name}" conflicts with the built-in ${label}.`);
 			if (prefixMatch) {
 				const prefix = name + "=";
 				for (const userName of optionNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined option "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 				for (const userName of commandNames) if (userName.startsWith(prefix)) throw new TypeError(`User-defined command "${userName}" conflicts with the built-in ${label} (prefix "${prefix}").`);
-				for (const literal of userNames.allLiterals) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
+				for (const literal of literalNames) if (literal.startsWith(prefix)) throw new TypeError(`Literal value "${literal}" conflicts with the built-in ${label} (prefix "${prefix}").`);
 			}
 		}
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1523+edc4d966",
+  "version": "1.0.0-dev.1533+25e020de",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",