@optique/core 0.8.0-dev.160 → 0.8.0-dev.164

package/dist/constructs.cjs

@@ -1030,9 +1030,273 @@ function group(label, parser) {
 		}
 	};
 }
+/**
+* Creates a conditional parser that selects different branch parsers based on
+* a discriminator option value. This enables discriminated union patterns where
+* certain options are only required or available when a specific discriminator
+* value is selected.
+*
+* The result type is a tuple: `[discriminatorValue, branchResult]`
+*
+* @example
+* ```typescript
+* // Basic conditional parsing
+* const parser = conditional(
+*   option("--reporter", choice(["console", "junit"])),
+*   {
+*     console: object({}),
+*     junit: object({ outputFile: option("--output-file", string()) }),
+*   },
+*   object({}) // default when --reporter is not provided
+* );
+*
+* const result = parse(parser, ["--reporter", "junit", "--output-file", "out.xml"]);
+* // result.value = ["junit", { outputFile: "out.xml" }]
+*
+* // Without --reporter, uses default branch:
+* const defaultResult = parse(parser, []);
+* // defaultResult.value = [undefined, {}]
+* ```
+*
+* @since 0.8.0
+*/
+function conditional(discriminator, branches, defaultBranch, options) {
+	const branchParsers = Object.entries(branches);
+	const allBranchParsers = defaultBranch ? [...branchParsers.map(([_, p]) => p), defaultBranch] : branchParsers.map(([_, p]) => p);
+	const maxPriority = Math.max(discriminator.priority, ...allBranchParsers.map((p) => p.priority));
+	function appendLiteralToUsage(usage$1, literalValue) {
+		const result = [];
+		for (const term of usage$1) if (term.type === "option" && term.metavar !== void 0) {
+			const { metavar: _,...optionWithoutMetavar } = term;
+			result.push(optionWithoutMetavar);
+			result.push({
+				type: "literal",
+				value: literalValue
+			});
+		} else if (term.type === "optional") result.push({
+			...term,
+			terms: appendLiteralToUsage(term.terms, literalValue)
+		});
+		else if (term.type === "multiple") result.push({
+			...term,
+			terms: appendLiteralToUsage(term.terms, literalValue)
+		});
+		else if (term.type === "exclusive") result.push({
+			...term,
+			terms: term.terms.map((t) => appendLiteralToUsage(t, literalValue))
+		});
+		else result.push(term);
+		return result;
+	}
+	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
+	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const usage = branchUsages.length > 1 ? [{
+		type: "exclusive",
+		terms: branchUsages
+	}] : branchUsages[0] ?? [];
+	const initialState = {
+		discriminatorState: discriminator.initialState,
+		discriminatorValue: void 0,
+		selectedBranch: void 0,
+		branchState: void 0
+	};
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: maxPriority,
+		usage,
+		initialState,
+		parse(context) {
+			const state = context.state ?? initialState;
+			if (state.selectedBranch !== void 0) {
+				const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+				const branchResult = branchParser.parse({
+					...context,
+					state: state.branchState,
+					usage: branchParser.usage
+				});
+				if (branchResult.success) return {
+					success: true,
+					next: {
+						...branchResult.next,
+						state: {
+							...state,
+							branchState: branchResult.next.state
+						}
+					},
+					consumed: branchResult.consumed
+				};
+				return branchResult;
+			}
+			const discriminatorResult = discriminator.parse({
+				...context,
+				state: state.discriminatorState
+			});
+			if (discriminatorResult.success && discriminatorResult.consumed.length > 0) {
+				const completionResult = discriminator.complete(discriminatorResult.next.state);
+				if (completionResult.success) {
+					const value = completionResult.value;
+					const branchParser = branches[value];
+					if (branchParser) {
+						const branchParseResult = branchParser.parse({
+							...context,
+							buffer: discriminatorResult.next.buffer,
+							optionsTerminated: discriminatorResult.next.optionsTerminated,
+							state: branchParser.initialState,
+							usage: branchParser.usage
+						});
+						if (branchParseResult.success) return {
+							success: true,
+							next: {
+								...branchParseResult.next,
+								state: {
+									discriminatorState: discriminatorResult.next.state,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: branchParseResult.next.state
+								}
+							},
+							consumed: [...discriminatorResult.consumed, ...branchParseResult.consumed]
+						};
+						return {
+							success: true,
+							next: {
+								...discriminatorResult.next,
+								state: {
+									discriminatorState: discriminatorResult.next.state,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: branchParser.initialState
+								}
+							},
+							consumed: discriminatorResult.consumed
+						};
+					}
+				}
+			}
+			if (defaultBranch !== void 0) {
+				const defaultResult = defaultBranch.parse({
+					...context,
+					state: state.branchState ?? defaultBranch.initialState,
+					usage: defaultBranch.usage
+				});
+				if (defaultResult.success && defaultResult.consumed.length > 0) return {
+					success: true,
+					next: {
+						...defaultResult.next,
+						state: {
+							...state,
+							selectedBranch: { kind: "default" },
+							branchState: defaultResult.next.state
+						}
+					},
+					consumed: defaultResult.consumed
+				};
+			}
+			const noMatchContext = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
+			const errorMessage = options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
+			return {
+				success: false,
+				consumed: 0,
+				error: errorMessage
+			};
+		},
+		complete(state) {
+			if (state.selectedBranch === void 0) {
+				if (defaultBranch !== void 0) {
+					const branchState = state.branchState ?? defaultBranch.initialState;
+					const defaultResult = defaultBranch.complete(branchState);
+					if (!defaultResult.success) return defaultResult;
+					return {
+						success: true,
+						value: [void 0, defaultResult.value]
+					};
+				}
+				return {
+					success: false,
+					error: require_message.message`Missing required discriminator option.`
+				};
+			}
+			const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			const branchResult = branchParser.complete(state.branchState);
+			if (!branchResult.success) {
+				if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
+					success: false,
+					error: options.errors.branchError(state.discriminatorValue, branchResult.error)
+				};
+				return branchResult;
+			}
+			const discriminatorValue = state.selectedBranch.kind === "default" ? void 0 : state.selectedBranch.key;
+			return {
+				success: true,
+				value: [discriminatorValue, branchResult.value]
+			};
+		},
+		suggest(context, prefix) {
+			const state = context.state ?? initialState;
+			const suggestions = [];
+			if (state.selectedBranch === void 0) {
+				suggestions.push(...discriminator.suggest({
+					...context,
+					state: state.discriminatorState
+				}, prefix));
+				if (defaultBranch !== void 0) suggestions.push(...defaultBranch.suggest({
+					...context,
+					state: state.branchState ?? defaultBranch.initialState
+				}, prefix));
+			} else {
+				const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+				suggestions.push(...branchParser.suggest({
+					...context,
+					state: state.branchState
+				}, prefix));
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
+		getDocFragments(_state, _defaultValue) {
+			const fragments = [];
+			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
+			fragments.push(...discriminatorFragments.fragments);
+			for (const [key, branchParser] of branchParsers) {
+				const branchFragments = branchParser.getDocFragments({ kind: "unavailable" }, void 0);
+				const entries = branchFragments.fragments.filter((f) => f.type === "entry");
+				for (const fragment of branchFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
+				if (entries.length > 0) fragments.push({
+					type: "section",
+					title: `Options when ${key}`,
+					entries
+				});
+			}
+			if (defaultBranch !== void 0) {
+				const defaultFragments = defaultBranch.getDocFragments({ kind: "unavailable" }, void 0);
+				const entries = defaultFragments.fragments.filter((f) => f.type === "entry");
+				for (const fragment of defaultFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
+				if (entries.length > 0) fragments.push({
+					type: "section",
+					title: "Default options",
+					entries
+				});
+			}
+			return { fragments };
+		}
+	};
+}
 
 //#endregion
 exports.concat = concat;
+exports.conditional = conditional;
 exports.group = group;
 exports.longestMatch = longestMatch;
 exports.merge = merge;

package/dist/constructs.d.cts

@@ -1258,5 +1258,93 @@ declare function concat<TA extends readonly unknown[], TB extends readonly unkno
  * @since 0.4.0
  */
 declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
+/**
+ * Tagged union type representing which branch is selected.
+ * Uses tagged union to avoid collision with discriminator values.
+ * @internal
+ */
+type SelectedBranch<TDiscriminator extends string> = {
+  readonly kind: "branch";
+  readonly key: TDiscriminator;
+} | {
+  readonly kind: "default";
+};
+/**
+ * State type for the conditional parser.
+ * @internal
+ */
+interface ConditionalState<TDiscriminator extends string> {
+  readonly discriminatorState: unknown;
+  readonly discriminatorValue: TDiscriminator | undefined;
+  readonly selectedBranch: SelectedBranch<TDiscriminator> | undefined;
+  readonly branchState: unknown;
+}
+/**
+ * Options for customizing error messages in the {@link conditional} combinator.
+ * @since 0.8.0
+ */
+interface ConditionalErrorOptions {
+  /**
+   * Custom error message when branch parser fails.
+   * Receives the discriminator value for context.
+   */
+  branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
+  /**
+   * Custom error message for no matching input.
+   */
+  noMatch?: Message | ((context: NoMatchContext) => Message);
+}
+/**
+ * Options for customizing the {@link conditional} combinator behavior.
+ * @since 0.8.0
+ */
+interface ConditionalOptions {
+  /**
+   * Custom error messages.
+   */
+  errors?: ConditionalErrorOptions;
+}
+/**
+ * Helper type to infer result type without default branch.
+ * @internal
+ */
+type ConditionalResultWithoutDefault<TDiscriminator extends string, TBranches extends Record<string, Parser<unknown, unknown>>> = { [K in keyof TBranches & string]: readonly [K, InferValue<TBranches[K]>] }[keyof TBranches & string];
+/**
+ * Helper type to infer result type with default branch.
+ * @internal
+ */
+type ConditionalResultWithDefault<TDiscriminator extends string, TBranches extends Record<string, Parser<unknown, unknown>>, TDefault extends Parser<unknown, unknown>> = ConditionalResultWithoutDefault<TDiscriminator, TBranches> | readonly [undefined, InferValue<TDefault>];
+/**
+ * Helper type to infer value type from a parser.
+ * @internal
+ */
+type InferValue<T> = T extends Parser<infer V, unknown> ? V : never;
+/**
+ * Creates a conditional parser without a default branch.
+ * The discriminator option is required; parsing fails if not provided.
+ *
+ * @template TDiscriminator The string literal union type of discriminator values.
+ * @template TBranches Record mapping discriminator values to branch parsers.
+ * @param discriminator Parser for the discriminator option (typically using choice()).
+ * @param branches Object mapping each discriminator value to its branch parser.
+ * @returns A parser that produces a tuple `[discriminatorValue, branchResult]`.
+ * @since 0.8.0
+ */
+declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<unknown, unknown> }>(discriminator: Parser<TDiscriminator, unknown>, branches: TBranches): Parser<ConditionalResultWithoutDefault<TDiscriminator, TBranches>, ConditionalState<TDiscriminator>>;
+/**
+ * Creates a conditional parser with a default branch.
+ * The default branch is used when the discriminator option is not provided.
+ *
+ * @template TDiscriminator The string literal union type of discriminator values.
+ * @template TBranches Record mapping discriminator values to branch parsers.
+ * @template TDefault The default branch parser type.
+ * @param discriminator Parser for the discriminator option (typically using choice()).
+ * @param branches Object mapping each discriminator value to its branch parser.
+ * @param defaultBranch Parser to use when discriminator is not provided.
+ * @param options Optional configuration for error messages.
+ * @returns A parser that produces a tuple `[discriminatorValue | undefined, branchResult]`.
+ * @since 0.8.0
+ */
+declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<unknown, unknown> }, TDefault extends Parser<unknown, unknown>>(discriminator: Parser<TDiscriminator, unknown>, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.d.ts

@@ -1258,5 +1258,93 @@ declare function concat<TA extends readonly unknown[], TB extends readonly unkno
  * @since 0.4.0
  */
 declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
+/**
+ * Tagged union type representing which branch is selected.
+ * Uses tagged union to avoid collision with discriminator values.
+ * @internal
+ */
+type SelectedBranch<TDiscriminator extends string> = {
+  readonly kind: "branch";
+  readonly key: TDiscriminator;
+} | {
+  readonly kind: "default";
+};
+/**
+ * State type for the conditional parser.
+ * @internal
+ */
+interface ConditionalState<TDiscriminator extends string> {
+  readonly discriminatorState: unknown;
+  readonly discriminatorValue: TDiscriminator | undefined;
+  readonly selectedBranch: SelectedBranch<TDiscriminator> | undefined;
+  readonly branchState: unknown;
+}
+/**
+ * Options for customizing error messages in the {@link conditional} combinator.
+ * @since 0.8.0
+ */
+interface ConditionalErrorOptions {
+  /**
+   * Custom error message when branch parser fails.
+   * Receives the discriminator value for context.
+   */
+  branchError?: (discriminatorValue: string | undefined, error: Message) => Message;
+  /**
+   * Custom error message for no matching input.
+   */
+  noMatch?: Message | ((context: NoMatchContext) => Message);
+}
+/**
+ * Options for customizing the {@link conditional} combinator behavior.
+ * @since 0.8.0
+ */
+interface ConditionalOptions {
+  /**
+   * Custom error messages.
+   */
+  errors?: ConditionalErrorOptions;
+}
+/**
+ * Helper type to infer result type without default branch.
+ * @internal
+ */
+type ConditionalResultWithoutDefault<TDiscriminator extends string, TBranches extends Record<string, Parser<unknown, unknown>>> = { [K in keyof TBranches & string]: readonly [K, InferValue<TBranches[K]>] }[keyof TBranches & string];
+/**
+ * Helper type to infer result type with default branch.
+ * @internal
+ */
+type ConditionalResultWithDefault<TDiscriminator extends string, TBranches extends Record<string, Parser<unknown, unknown>>, TDefault extends Parser<unknown, unknown>> = ConditionalResultWithoutDefault<TDiscriminator, TBranches> | readonly [undefined, InferValue<TDefault>];
+/**
+ * Helper type to infer value type from a parser.
+ * @internal
+ */
+type InferValue<T> = T extends Parser<infer V, unknown> ? V : never;
+/**
+ * Creates a conditional parser without a default branch.
+ * The discriminator option is required; parsing fails if not provided.
+ *
+ * @template TDiscriminator The string literal union type of discriminator values.
+ * @template TBranches Record mapping discriminator values to branch parsers.
+ * @param discriminator Parser for the discriminator option (typically using choice()).
+ * @param branches Object mapping each discriminator value to its branch parser.
+ * @returns A parser that produces a tuple `[discriminatorValue, branchResult]`.
+ * @since 0.8.0
+ */
+declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<unknown, unknown> }>(discriminator: Parser<TDiscriminator, unknown>, branches: TBranches): Parser<ConditionalResultWithoutDefault<TDiscriminator, TBranches>, ConditionalState<TDiscriminator>>;
+/**
+ * Creates a conditional parser with a default branch.
+ * The default branch is used when the discriminator option is not provided.
+ *
+ * @template TDiscriminator The string literal union type of discriminator values.
+ * @template TBranches Record mapping discriminator values to branch parsers.
+ * @template TDefault The default branch parser type.
+ * @param discriminator Parser for the discriminator option (typically using choice()).
+ * @param branches Object mapping each discriminator value to its branch parser.
+ * @param defaultBranch Parser to use when discriminator is not provided.
+ * @param options Optional configuration for error messages.
+ * @returns A parser that produces a tuple `[discriminatorValue | undefined, branchResult]`.
+ * @since 0.8.0
+ */
+declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<unknown, unknown> }, TDefault extends Parser<unknown, unknown>>(discriminator: Parser<TDiscriminator, unknown>, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/constructs.js

@@ -1030,6 +1030,269 @@ function group(label, parser) {
 		}
 	};
 }
+/**
+* Creates a conditional parser that selects different branch parsers based on
+* a discriminator option value. This enables discriminated union patterns where
+* certain options are only required or available when a specific discriminator
+* value is selected.
+*
+* The result type is a tuple: `[discriminatorValue, branchResult]`
+*
+* @example
+* ```typescript
+* // Basic conditional parsing
+* const parser = conditional(
+*   option("--reporter", choice(["console", "junit"])),
+*   {
+*     console: object({}),
+*     junit: object({ outputFile: option("--output-file", string()) }),
+*   },
+*   object({}) // default when --reporter is not provided
+* );
+*
+* const result = parse(parser, ["--reporter", "junit", "--output-file", "out.xml"]);
+* // result.value = ["junit", { outputFile: "out.xml" }]
+*
+* // Without --reporter, uses default branch:
+* const defaultResult = parse(parser, []);
+* // defaultResult.value = [undefined, {}]
+* ```
+*
+* @since 0.8.0
+*/
+function conditional(discriminator, branches, defaultBranch, options) {
+	const branchParsers = Object.entries(branches);
+	const allBranchParsers = defaultBranch ? [...branchParsers.map(([_, p]) => p), defaultBranch] : branchParsers.map(([_, p]) => p);
+	const maxPriority = Math.max(discriminator.priority, ...allBranchParsers.map((p) => p.priority));
+	function appendLiteralToUsage(usage$1, literalValue) {
+		const result = [];
+		for (const term of usage$1) if (term.type === "option" && term.metavar !== void 0) {
+			const { metavar: _,...optionWithoutMetavar } = term;
+			result.push(optionWithoutMetavar);
+			result.push({
+				type: "literal",
+				value: literalValue
+			});
+		} else if (term.type === "optional") result.push({
+			...term,
+			terms: appendLiteralToUsage(term.terms, literalValue)
+		});
+		else if (term.type === "multiple") result.push({
+			...term,
+			terms: appendLiteralToUsage(term.terms, literalValue)
+		});
+		else if (term.type === "exclusive") result.push({
+			...term,
+			terms: term.terms.map((t) => appendLiteralToUsage(t, literalValue))
+		});
+		else result.push(term);
+		return result;
+	}
+	const branchUsages = branchParsers.map(([key, p]) => [...appendLiteralToUsage(discriminator.usage, key), ...p.usage]);
+	if (defaultBranch) branchUsages.push(defaultBranch.usage);
+	const usage = branchUsages.length > 1 ? [{
+		type: "exclusive",
+		terms: branchUsages
+	}] : branchUsages[0] ?? [];
+	const initialState = {
+		discriminatorState: discriminator.initialState,
+		discriminatorValue: void 0,
+		selectedBranch: void 0,
+		branchState: void 0
+	};
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: maxPriority,
+		usage,
+		initialState,
+		parse(context) {
+			const state = context.state ?? initialState;
+			if (state.selectedBranch !== void 0) {
+				const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+				const branchResult = branchParser.parse({
+					...context,
+					state: state.branchState,
+					usage: branchParser.usage
+				});
+				if (branchResult.success) return {
+					success: true,
+					next: {
+						...branchResult.next,
+						state: {
+							...state,
+							branchState: branchResult.next.state
+						}
+					},
+					consumed: branchResult.consumed
+				};
+				return branchResult;
+			}
+			const discriminatorResult = discriminator.parse({
+				...context,
+				state: state.discriminatorState
+			});
+			if (discriminatorResult.success && discriminatorResult.consumed.length > 0) {
+				const completionResult = discriminator.complete(discriminatorResult.next.state);
+				if (completionResult.success) {
+					const value = completionResult.value;
+					const branchParser = branches[value];
+					if (branchParser) {
+						const branchParseResult = branchParser.parse({
+							...context,
+							buffer: discriminatorResult.next.buffer,
+							optionsTerminated: discriminatorResult.next.optionsTerminated,
+							state: branchParser.initialState,
+							usage: branchParser.usage
+						});
+						if (branchParseResult.success) return {
+							success: true,
+							next: {
+								...branchParseResult.next,
+								state: {
+									discriminatorState: discriminatorResult.next.state,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: branchParseResult.next.state
+								}
+							},
+							consumed: [...discriminatorResult.consumed, ...branchParseResult.consumed]
+						};
+						return {
+							success: true,
+							next: {
+								...discriminatorResult.next,
+								state: {
+									discriminatorState: discriminatorResult.next.state,
+									discriminatorValue: value,
+									selectedBranch: {
+										kind: "branch",
+										key: value
+									},
+									branchState: branchParser.initialState
+								}
+							},
+							consumed: discriminatorResult.consumed
+						};
+					}
+				}
+			}
+			if (defaultBranch !== void 0) {
+				const defaultResult = defaultBranch.parse({
+					...context,
+					state: state.branchState ?? defaultBranch.initialState,
+					usage: defaultBranch.usage
+				});
+				if (defaultResult.success && defaultResult.consumed.length > 0) return {
+					success: true,
+					next: {
+						...defaultResult.next,
+						state: {
+							...state,
+							selectedBranch: { kind: "default" },
+							branchState: defaultResult.next.state
+						}
+					},
+					consumed: defaultResult.consumed
+				};
+			}
+			const noMatchContext = analyzeNoMatchContext([discriminator, ...allBranchParsers]);
+			const errorMessage = options?.errors?.noMatch ? typeof options.errors.noMatch === "function" ? options.errors.noMatch(noMatchContext) : options.errors.noMatch : generateNoMatchError(noMatchContext);
+			return {
+				success: false,
+				consumed: 0,
+				error: errorMessage
+			};
+		},
+		complete(state) {
+			if (state.selectedBranch === void 0) {
+				if (defaultBranch !== void 0) {
+					const branchState = state.branchState ?? defaultBranch.initialState;
+					const defaultResult = defaultBranch.complete(branchState);
+					if (!defaultResult.success) return defaultResult;
+					return {
+						success: true,
+						value: [void 0, defaultResult.value]
+					};
+				}
+				return {
+					success: false,
+					error: message`Missing required discriminator option.`
+				};
+			}
+			const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+			const branchResult = branchParser.complete(state.branchState);
+			if (!branchResult.success) {
+				if (state.discriminatorValue !== void 0 && options?.errors?.branchError) return {
+					success: false,
+					error: options.errors.branchError(state.discriminatorValue, branchResult.error)
+				};
+				return branchResult;
+			}
+			const discriminatorValue = state.selectedBranch.kind === "default" ? void 0 : state.selectedBranch.key;
+			return {
+				success: true,
+				value: [discriminatorValue, branchResult.value]
+			};
+		},
+		suggest(context, prefix) {
+			const state = context.state ?? initialState;
+			const suggestions = [];
+			if (state.selectedBranch === void 0) {
+				suggestions.push(...discriminator.suggest({
+					...context,
+					state: state.discriminatorState
+				}, prefix));
+				if (defaultBranch !== void 0) suggestions.push(...defaultBranch.suggest({
+					...context,
+					state: state.branchState ?? defaultBranch.initialState
+				}, prefix));
+			} else {
+				const branchParser = state.selectedBranch.kind === "default" ? defaultBranch : branches[state.selectedBranch.key];
+				suggestions.push(...branchParser.suggest({
+					...context,
+					state: state.branchState
+				}, prefix));
+			}
+			const seen = /* @__PURE__ */ new Set();
+			return suggestions.filter((suggestion) => {
+				const key = suggestion.kind === "literal" ? suggestion.text : `__FILE__:${suggestion.type}:${suggestion.extensions?.join(",")}`;
+				if (seen.has(key)) return false;
+				seen.add(key);
+				return true;
+			});
+		},
+		getDocFragments(_state, _defaultValue) {
+			const fragments = [];
+			const discriminatorFragments = discriminator.getDocFragments({ kind: "unavailable" }, void 0);
+			fragments.push(...discriminatorFragments.fragments);
+			for (const [key, branchParser] of branchParsers) {
+				const branchFragments = branchParser.getDocFragments({ kind: "unavailable" }, void 0);
+				const entries = branchFragments.fragments.filter((f) => f.type === "entry");
+				for (const fragment of branchFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
+				if (entries.length > 0) fragments.push({
+					type: "section",
+					title: `Options when ${key}`,
+					entries
+				});
+			}
+			if (defaultBranch !== void 0) {
+				const defaultFragments = defaultBranch.getDocFragments({ kind: "unavailable" }, void 0);
+				const entries = defaultFragments.fragments.filter((f) => f.type === "entry");
+				for (const fragment of defaultFragments.fragments) if (fragment.type === "section") entries.push(...fragment.entries);
+				if (entries.length > 0) fragments.push({
+					type: "section",
+					title: "Default options",
+					entries
+				});
+			}
+			return { fragments };
+		}
+	};
+}
 
 //#endregion
-export { concat, group, longestMatch, merge, object, or, tuple };
+export { concat, conditional, group, longestMatch, merge, object, or, tuple };

package/dist/index.cjs

@@ -17,6 +17,7 @@ exports.choice = require_valueparser.choice;
 exports.command = require_primitives.command;
 exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
+exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
 exports.envVar = require_message.envVar;
 exports.extractArgumentMetavars = require_usage.extractArgumentMetavars;

package/dist/index.d.cts

@@ -5,7 +5,7 @@ import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.cjs";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
 import { DocState, InferValue, Parser, ParserContext, ParserResult, Result, Suggestion, getDocPage, parse, suggest } from "./parser.js";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShellCompletion, ShowDefaultOptions, StringOptions, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/index.js

@@ -1,6 +1,6 @@
 import { commandLine, envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
-import { concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatDocPage } from "./doc.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
@@ -9,4 +9,4 @@ import { argument, command, constant, flag, option } from "./primitives.js";
 import { getDocPage, parse, suggest } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };
+export { RunError, WithDefaultError, argument, bash, choice, command, commandLine, concat, conditional, constant, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, pwsh, run, string, suggest, text, tuple, url, uuid, value, values, withDefault, zsh };

package/dist/modifiers.cjs

@@ -23,18 +23,29 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
 			const result = parser.parse({
 				...context,
-				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+				state: innerState
 			});
-			if (result.success) return {
-				success: true,
-				next: {
-					...result.next,
-					state: [result.next.state]
-				},
-				consumed: result.consumed
-			};
+			if (result.success) {
+				if (result.next.state !== innerState || result.consumed.length === 0) return {
+					success: true,
+					next: {
+						...result.next,
+						state: [result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return {
+					success: true,
+					next: {
+						...result.next,
+						state: context.state
+					},
+					consumed: result.consumed
+				};
+			}
 			if (result.consumed === 0) return {
 				success: true,
 				next: context,
@@ -110,18 +121,29 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
 			const result = parser.parse({
 				...context,
-				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+				state: innerState
 			});
-			if (result.success) return {
-				success: true,
-				next: {
-					...result.next,
-					state: [result.next.state]
-				},
-				consumed: result.consumed
-			};
+			if (result.success) {
+				if (result.next.state !== innerState || result.consumed.length === 0) return {
+					success: true,
+					next: {
+						...result.next,
+						state: [result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return {
+					success: true,
+					next: {
+						...result.next,
+						state: context.state
+					},
+					consumed: result.consumed
+				};
+			}
 			if (result.consumed === 0) return {
 				success: true,
 				next: context,

package/dist/modifiers.js

@@ -23,18 +23,29 @@ function optional(parser) {
 		}],
 		initialState: void 0,
 		parse(context) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
 			const result = parser.parse({
 				...context,
-				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+				state: innerState
 			});
-			if (result.success) return {
-				success: true,
-				next: {
-					...result.next,
-					state: [result.next.state]
-				},
-				consumed: result.consumed
-			};
+			if (result.success) {
+				if (result.next.state !== innerState || result.consumed.length === 0) return {
+					success: true,
+					next: {
+						...result.next,
+						state: [result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return {
+					success: true,
+					next: {
+						...result.next,
+						state: context.state
+					},
+					consumed: result.consumed
+				};
+			}
 			if (result.consumed === 0) return {
 				success: true,
 				next: context,
@@ -110,18 +121,29 @@ function withDefault(parser, defaultValue, options) {
 		}],
 		initialState: void 0,
 		parse(context) {
+			const innerState = typeof context.state === "undefined" ? parser.initialState : context.state[0];
 			const result = parser.parse({
 				...context,
-				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+				state: innerState
 			});
-			if (result.success) return {
-				success: true,
-				next: {
-					...result.next,
-					state: [result.next.state]
-				},
-				consumed: result.consumed
-			};
+			if (result.success) {
+				if (result.next.state !== innerState || result.consumed.length === 0) return {
+					success: true,
+					next: {
+						...result.next,
+						state: [result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return {
+					success: true,
+					next: {
+						...result.next,
+						state: context.state
+					},
+					consumed: result.consumed
+				};
+			}
 			if (result.consumed === 0) return {
 				success: true,
 				next: context,

package/dist/parser.cjs

@@ -176,6 +176,7 @@ exports.WithDefaultError = require_modifiers.WithDefaultError;
 exports.argument = require_primitives.argument;
 exports.command = require_primitives.command;
 exports.concat = require_constructs.concat;
+exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
 exports.flag = require_primitives.flag;
 exports.getDocPage = getDocPage;

package/dist/parser.d.cts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.cjs";
 import { ValueParserResult } from "./valueparser.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.cjs";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
+import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/parser.d.ts

@@ -4,7 +4,7 @@ import { DocFragments, DocPage } from "./doc.js";
 import { ValueParserResult } from "./valueparser.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option } from "./primitives.js";
-import { LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { ConditionalErrorOptions, ConditionalOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 
 //#region src/parser.d.ts
 
@@ -323,4 +323,4 @@ declare function suggest<T>(parser: Parser<T, unknown>, args: readonly [string,
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, FlagErrorOptions, FlagOptions, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/parser.js

@@ -1,6 +1,6 @@
 import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
-import { concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 
@@ -172,4 +172,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };
+export { WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, suggest, tuple, withDefault };

package/dist/usage.cjs

@@ -327,7 +327,11 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
 			width: 1
 		};
-	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	} else if (term.type === "literal") yield {
+		text: term.value,
+		width: term.value.length
+	};
+	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/dist/usage.d.cts

@@ -108,6 +108,21 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+}
+/**
+ * A literal term, which represents a fixed string value in the command-line
+ * usage. Unlike metavars which are placeholders for user-provided values,
+ * literals represent exact strings that must be typed as-is.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"literal"` for this term.
+   */
+  readonly type: "literal";
+  /**
+   * The literal value that must be provided exactly as written.
+   */
+  readonly value: string;
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.d.ts

@@ -108,6 +108,21 @@ type UsageTerm =
    * arguments, options, commands, or other usage terms.
    */
   readonly terms: readonly Usage[];
+}
+/**
+ * A literal term, which represents a fixed string value in the command-line
+ * usage. Unlike metavars which are placeholders for user-provided values,
+ * literals represent exact strings that must be typed as-is.
+ * @since 0.8.0
+ */ | {
+  /**
+   * The type of the term, which is always `"literal"` for this term.
+   */
+  readonly type: "literal";
+  /**
+   * The literal value that must be provided exactly as written.
+   */
+  readonly value: string;
 };
 /**
  * Represents a command-line usage description, which is a sequence of

package/dist/usage.js

@@ -326,7 +326,11 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
 			width: 1
 		};
-	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+	} else if (term.type === "literal") yield {
+		text: term.value,
+		width: term.value.length
+	};
+	else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.8.0-dev.160+4ae9b5c5",
+  "version": "0.8.0-dev.164+250237ef",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",