@optique/core 1.3.0-dev.2366 → 1.3.0-dev.2375

package/dist/internal/parser.d.ts

@@ -42,6 +42,51 @@ type ModeValue<M extends Mode, T> = M extends "async" ? Promise<T> : T;
  * @since 0.9.0
  */
 type ModeIterable<M extends Mode, T> = M extends "async" ? AsyncIterable<T> : Iterable<T>;
+/**
+ * Internal symbol used by transparent combinators to expose independently
+ * competing parse operations to shared-buffer parents.
+ * @internal
+ */
+declare const parseLanesKey: unique symbol;
+/**
+ * An owner-consumption requirement for a parse lane.
+ * @internal
+ */
+interface ParseLaneConsumptionGroup {
+  /** Identity shared by lanes belonging to the same owning parser. */
+  readonly id: object;
+  /** Whether the owning parser is active after a consuming lane succeeds. */
+  readonly isActive?: (state: unknown) => boolean;
+}
+/**
+ * A state-preserving parse operation that competes at one exact priority.
+ * @internal
+ */
+interface ParseLane<TState> {
+  /** The exact priority at which this lane competes. */
+  readonly priority: number;
+  /**
+   * Identity shared by lanes that must all succeed before their
+   * zero-consumption state updates can be committed.
+   */
+  readonly zeroConsumptionGroup?: object;
+  /**
+   * Whether a zero-consumption success can settle the owning parser while
+   * input remains.  Defaults to `true`.
+   */
+  readonly settlesZeroConsumption?: boolean;
+  /** Fixed tokens reachable through this lane. */
+  readonly leadingNames: ReadonlySet<string>;
+  /** Whether this lane accepts any positional token. */
+  readonly acceptingAnyToken: boolean;
+  /**
+   * Groups in which a zero-consumption update is valid only after another
+   * lane in every group has consumed input during the same arbitration.
+   */
+  readonly requiredConsumptionGroups?: readonly ParseLaneConsumptionGroup[];
+  /** Parses through the owning parser's state and execution context. */
+  parse(context: ParserContext<TState>): ParserResult<TState> | Promise<ParserResult<TState>>;
+}
 /**
  * Combines multiple modes into a single mode.
  * If any mode is `"async"`, the result is `"async"`; otherwise `"sync"`.
@@ -851,6 +896,22 @@ declare function getDelegatingSuggestRuntimeNodes<TInnerState>(innerParser: Pars
  * @internal
  */
 declare function composeWrappedSourceMetadata(dependencyMetadata: ParserDependencyMetadata | undefined, wrapSource: (source: NonNullable<ParserDependencyMetadata["source"]>) => NonNullable<ParserDependencyMetadata["source"]>): ParserDependencyMetadata | undefined;
+/**
+ * Defines internal parse-lane metadata without exposing it through object
+ * spreads used by custom parser wrappers.
+ *
+ * @internal
+ */
+declare function defineParseLanes<TState>(parser: object, lanes: readonly ParseLane<TState>[] | undefined): void;
+/**
+ * Gets parse-lane metadata defined directly on a parser.
+ *
+ * Inherited metadata belongs to the parser's prototype and must not bypass an
+ * overriding `parse()` implementation on a custom wrapper.
+ *
+ * @internal
+ */
+declare function getOwnParseLanes<TState>(parser: object): readonly ParseLane<TState>[] | undefined;
 /**
  * Marks a parser as inheriting parent-state annotations through wrapper-state
  * reconstruction.
@@ -999,4 +1060,4 @@ declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOpti
 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 { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, ParseLane, ParseLaneConsumptionGroup, type ParseOptions, Parser, ParserContext, ParserResult, Result, Suggestion, annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/internal/parser.js

@@ -8,6 +8,12 @@ import { createInputTrace } from "../input-trace.js";
 
 //#region src/internal/parser.ts
 /**
+* Internal symbol used by transparent combinators to expose independently
+* competing parse operations to shared-buffer parents.
+* @internal
+*/
+const parseLanesKey = Symbol("parseLanes");
+/**
 * Internal marker for wrappers whose `{ hasCliValue: false }` states should
 * be treated as unmatched dependency-source states during completion-time
 * Phase 1.
@@ -387,6 +393,32 @@ function composeWrappedSourceMetadata(dependencyMetadata, wrapSource) {
 	};
 }
 /**
+* Defines internal parse-lane metadata without exposing it through object
+* spreads used by custom parser wrappers.
+*
+* @internal
+*/
+function defineParseLanes(parser, lanes) {
+	if (lanes == null) return;
+	Object.defineProperty(parser, parseLanesKey, {
+		value: lanes,
+		configurable: true,
+		enumerable: false
+	});
+}
+/**
+* Gets parse-lane metadata defined directly on a parser.
+*
+* Inherited metadata belongs to the parser's prototype and must not bypass an
+* overriding `parse()` implementation on a custom wrapper.
+*
+* @internal
+*/
+function getOwnParseLanes(parser) {
+	if (!Object.hasOwn(parser, parseLanesKey)) return void 0;
+	return parser[parseLanesKey];
+}
+/**
 * Marks a parser as inheriting parent-state annotations through wrapper-state
 * reconstruction.
 *
@@ -850,4 +882,4 @@ function findNextMatchedCommandArgIndex(args, matchedCommandArgIndices, start) {
 }
 
 //#endregion
-export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };
+export { annotationWrapperRequiresSourceBindingKey, composeWrappedSourceMetadata, createParserContext, defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getDelegatingSuggestRuntimeNodes, getDocPage, getDocPageAsync, getDocPageSync, getOwnParseLanes, getParserSuggestRuntimeNodes, inheritParentAnnotationsKey, parse, parseAsync, parseLanesKey, parseSync, suggest, suggestAsync, suggestSync, unmatchedNonCliDependencySourceStateMarker };

package/dist/modifiers.cjs

@@ -231,6 +231,44 @@ function processOptionalStyleResult(result, innerState, context) {
 	};
 	return result;
 }
+function adaptOptionalStyleParseLanes(parser) {
+	const lanes = require_internal_parser.getOwnParseLanes(parser);
+	if (lanes == null) return void 0;
+	const consumptionGroup = {};
+	return lanes.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: false,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups?.map((group) => ({
+			id: group.id,
+			...group.isActive == null ? {} : { isActive(state) {
+				const innerState = Array.isArray(state) ? state[0] : parser.initialState;
+				return group.isActive?.(innerState) ?? true;
+			} }
+		})) ?? [], {
+			id: consumptionGroup,
+			isActive(state) {
+				return Array.isArray(state);
+			}
+		}],
+		parse(context) {
+			const innerState = deriveOptionalInnerParseState(context.state, parser);
+			const innerContext = {
+				...context,
+				state: innerState
+			};
+			return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+				const result = lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			}, async () => {
+				const result = await lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			});
+		}
+	}));
+}
 /**
 * Creates a `shouldDeferCompletion` adapter that unwraps the outer state
 * shape (`[TState] | undefined`) used by {@link optional} and
@@ -420,6 +458,7 @@ function optional(parser) {
 		const composed = require_dependency_metadata.composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	require_internal_parser.defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return fluent(optionalParser);
@@ -654,6 +693,7 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	require_internal_parser.defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return fluent(withDefaultParser);
@@ -793,6 +833,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	require_internal_parser.defineParseLanes(mappedParser, require_internal_parser.getOwnParseLanes(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1680,6 +1721,7 @@ function multiple(parser, options = {}) {
 function nonEmpty(parser) {
 	const syncParser = parser;
 	const initialState = parser.initialState;
+	const consumptionGroup = {};
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1732,6 +1774,17 @@ function nonEmpty(parser) {
 			return syncParser.getDocFragments(state, defaultValue);
 		}
 	};
+	require_internal_parser.defineParseLanes(nonEmptyParser, require_internal_parser.getOwnParseLanes(parser)?.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: lane.acceptingAnyToken,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups ?? [], { id: consumptionGroup }],
+		parse(context) {
+			return lane.parse(context);
+		}
+	})));
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;

package/dist/modifiers.js

@@ -1,7 +1,7 @@
 import { annotateFreshArray, annotationKey, getAnnotations, inheritAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { formatMessage, message, text } from "./message.js";
 import { dispatchByMode, dispatchIterableByMode, mapModeValue, wrapForMode } from "./internal/mode-dispatch.js";
-import { defineInheritedAnnotationParser, defineSourceBindingOnlyAnnotationCompletionParser, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
+import { defineInheritedAnnotationParser, defineParseLanes, defineSourceBindingOnlyAnnotationCompletionParser, getOwnParseLanes, unmatchedNonCliDependencySourceStateMarker } from "./internal/parser.js";
 import { getDelegatedAnnotationState, hasDelegatedAnnotationCarrier, isAnnotationWrappedInitialState, normalizeDelegatedAnnotationState, normalizeNestedDelegatedAnnotationState } from "./annotation-state.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult } from "./phase2-seed.js";
@@ -231,6 +231,44 @@ function processOptionalStyleResult(result, innerState, context) {
 	};
 	return result;
 }
+function adaptOptionalStyleParseLanes(parser) {
+	const lanes = getOwnParseLanes(parser);
+	if (lanes == null) return void 0;
+	const consumptionGroup = {};
+	return lanes.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: false,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups?.map((group) => ({
+			id: group.id,
+			...group.isActive == null ? {} : { isActive(state) {
+				const innerState = Array.isArray(state) ? state[0] : parser.initialState;
+				return group.isActive?.(innerState) ?? true;
+			} }
+		})) ?? [], {
+			id: consumptionGroup,
+			isActive(state) {
+				return Array.isArray(state);
+			}
+		}],
+		parse(context) {
+			const innerState = deriveOptionalInnerParseState(context.state, parser);
+			const innerContext = {
+				...context,
+				state: innerState
+			};
+			return dispatchByMode(parser.mode, () => {
+				const result = lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			}, async () => {
+				const result = await lane.parse(innerContext);
+				return processOptionalStyleResult(result, innerState, context);
+			});
+		}
+	}));
+}
 /**
 * Creates a `shouldDeferCompletion` adapter that unwraps the outer state
 * shape (`[TState] | undefined`) used by {@link optional} and
@@ -420,6 +458,7 @@ function optional(parser) {
 		const composed = composeDependencyMetadata(parser.dependencyMetadata, "optional");
 		if (composed != null) optionalParser.dependencyMetadata = composed;
 	}
+	defineParseLanes(optionalParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(optionalParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
 	return fluent(optionalParser);
@@ -654,6 +693,7 @@ function withDefault(parser, defaultValue, options) {
 		} });
 		if (composed != null) withDefaultParser.dependencyMetadata = composed;
 	}
+	defineParseLanes(withDefaultParser, adaptOptionalStyleParseLanes(parser));
 	defineInheritedAnnotationParser(withDefaultParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
 	return fluent(withDefaultParser);
@@ -793,6 +833,7 @@ function map(parser, transform) {
 			return parser.getDocFragments(state, void 0);
 		}
 	};
+	defineParseLanes(mappedParser, getOwnParseLanes(parser));
 	delete mappedParser.normalizeValue;
 	delete mappedParser.validateValue;
 	if ("placeholder" in parser) Object.defineProperty(mappedParser, "placeholder", {
@@ -1680,6 +1721,7 @@ function multiple(parser, options = {}) {
 function nonEmpty(parser) {
 	const syncParser = parser;
 	const initialState = parser.initialState;
+	const consumptionGroup = {};
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1732,6 +1774,17 @@ function nonEmpty(parser) {
 			return syncParser.getDocFragments(state, defaultValue);
 		}
 	};
+	defineParseLanes(nonEmptyParser, getOwnParseLanes(parser)?.map((lane) => ({
+		priority: lane.priority,
+		zeroConsumptionGroup: lane.zeroConsumptionGroup,
+		settlesZeroConsumption: lane.settlesZeroConsumption,
+		leadingNames: lane.leadingNames,
+		acceptingAnyToken: lane.acceptingAnyToken,
+		requiredConsumptionGroups: [...lane.requiredConsumptionGroups ?? [], { id: consumptionGroup }],
+		parse(context) {
+			return lane.parse(context);
+		}
+	})));
 	if ("placeholder" in parser) Object.defineProperty(nonEmptyParser, "placeholder", {
 		get() {
 			return parser.placeholder;

package/dist/valueparser.cjs

@@ -620,6 +620,71 @@ function string(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} that compiles regular expression sources.
+*
+* The entire input is treated as the source.  Slash-delimited notation such
+* as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+* configure fixed flags for the parser.
+*
+* **Security note**: Compiling a source does not establish that it is safe to
+* execute.  Patterns from untrusted input can cause Regular Expression Denial
+* of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+* matches in an environment that can be terminated, or use a linear-time
+* regular expression engine when accepting untrusted patterns.
+*
+* @param options Configuration options for the regular expression parser.
+* @returns A sync value parser producing JavaScript {@link RegExp} objects.
+* @throws {TypeError} If `options.metavar` is an empty string or
+*   `options.flags` is not a string.
+* @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+*   incompatible regular expression flags.
+* @since 1.3.0
+*/
+function regExp(options = {}) {
+	const metavar$1 = options.metavar ?? "REGEXP";
+	require_nonempty.ensureNonEmptyString(metavar$1);
+	if (options.flags !== void 0 && typeof options.flags !== "string") throw new TypeError(`Expected flags to be a string, but got ${typeof options.flags}: ${String(options.flags)}.`);
+	const flags = new RegExp("", options.flags ?? "").flags;
+	const invalidRegExp = options.errors?.invalidRegExp;
+	const parseRegExp = (input) => {
+		try {
+			return {
+				success: true,
+				value: new RegExp(input, flags)
+			};
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+			return {
+				success: false,
+				error: invalidRegExp ? typeof invalidRegExp === "function" ? invalidRegExp(input) : invalidRegExp : require_message.message`Invalid regular expression: ${input}.`
+			};
+		}
+	};
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new RegExp("", flags);
+		},
+		parse: parseRegExp,
+		validate(value) {
+			if (!(value instanceof RegExp)) return {
+				success: false,
+				error: require_message.message`Expected a RegExp value.`
+			};
+			return parseRegExp(value.source);
+		},
+		normalize(value) {
+			if (!(value instanceof RegExp)) return value;
+			const result = parseRegExp(value.source);
+			return result.success ? result.value : value;
+		},
+		format(value) {
+			return value.source;
+		}
+	};
+}
 function keyValue(options = {}) {
 	const separator = options.separator ?? "=";
 	if (typeof separator !== "string") throw new TypeError(`Expected separator to be a string, but got ${typeof separator}: ${String(separator)}.`);
@@ -6628,6 +6693,7 @@ exports.locale = locale;
 exports.macAddress = macAddress;
 exports.port = port;
 exports.portRange = portRange;
+exports.regExp = regExp;
 exports.semVer = semVer;
 exports.socketAddress = socketAddress;
 exports.string = string;

package/dist/valueparser.d.cts

@@ -498,6 +498,64 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+/**
+ * Options for creating a {@link regExp} value parser.
+ *
+ * @since 1.3.0
+ */
+interface RegExpOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"REGEXP"`
+   * @since 1.3.0
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Fixed flags used to compile every input source.
+   * @default `""`
+   * @since 1.3.0
+   */
+  readonly flags?: string;
+  /**
+   * Custom error messages for regular expression parsing failures.
+   * @since 1.3.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid regular expression
+     * source.  Can be a static message or a function that receives the input.
+     *
+     * **Security note**: Successful compilation does not guarantee safe
+     * execution. Vulnerable patterns can cause catastrophic backtracking when
+     * later matched against untrusted data.
+     * @since 1.3.0
+     */
+    readonly invalidRegExp?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that compiles regular expression sources.
+ *
+ * The entire input is treated as the source.  Slash-delimited notation such
+ * as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+ * configure fixed flags for the parser.
+ *
+ * **Security note**: Compiling a source does not establish that it is safe to
+ * execute.  Patterns from untrusted input can cause Regular Expression Denial
+ * of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+ * matches in an environment that can be terminated, or use a linear-time
+ * regular expression engine when accepting untrusted patterns.
+ *
+ * @param options Configuration options for the regular expression parser.
+ * @returns A sync value parser producing JavaScript {@link RegExp} objects.
+ * @throws {TypeError} If `options.metavar` is an empty string or
+ *   `options.flags` is not a string.
+ * @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+ *   incompatible regular expression flags.
+ * @since 1.3.0
+ */
+declare function regExp(options?: RegExpOptions): ValueParser<"sync", RegExp>;
 interface KeyValueOptionsBase {
   /**
    * The metavariable name for this parser.  Used in help messages to
@@ -3279,4 +3337,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.d.ts

@@ -498,6 +498,64 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+/**
+ * Options for creating a {@link regExp} value parser.
+ *
+ * @since 1.3.0
+ */
+interface RegExpOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"REGEXP"`
+   * @since 1.3.0
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Fixed flags used to compile every input source.
+   * @default `""`
+   * @since 1.3.0
+   */
+  readonly flags?: string;
+  /**
+   * Custom error messages for regular expression parsing failures.
+   * @since 1.3.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid regular expression
+     * source.  Can be a static message or a function that receives the input.
+     *
+     * **Security note**: Successful compilation does not guarantee safe
+     * execution. Vulnerable patterns can cause catastrophic backtracking when
+     * later matched against untrusted data.
+     * @since 1.3.0
+     */
+    readonly invalidRegExp?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that compiles regular expression sources.
+ *
+ * The entire input is treated as the source.  Slash-delimited notation such
+ * as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+ * configure fixed flags for the parser.
+ *
+ * **Security note**: Compiling a source does not establish that it is safe to
+ * execute.  Patterns from untrusted input can cause Regular Expression Denial
+ * of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+ * matches in an environment that can be terminated, or use a linear-time
+ * regular expression engine when accepting untrusted patterns.
+ *
+ * @param options Configuration options for the regular expression parser.
+ * @returns A sync value parser producing JavaScript {@link RegExp} objects.
+ * @throws {TypeError} If `options.metavar` is an empty string or
+ *   `options.flags` is not a string.
+ * @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+ *   incompatible regular expression flags.
+ * @since 1.3.0
+ */
+declare function regExp(options?: RegExpOptions): ValueParser<"sync", RegExp>;
 interface KeyValueOptionsBase {
   /**
    * The metavariable name for this parser.  Used in help messages to
@@ -3279,4 +3337,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.js

@@ -620,6 +620,71 @@ function string(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} that compiles regular expression sources.
+*
+* The entire input is treated as the source.  Slash-delimited notation such
+* as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+* configure fixed flags for the parser.
+*
+* **Security note**: Compiling a source does not establish that it is safe to
+* execute.  Patterns from untrusted input can cause Regular Expression Denial
+* of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+* matches in an environment that can be terminated, or use a linear-time
+* regular expression engine when accepting untrusted patterns.
+*
+* @param options Configuration options for the regular expression parser.
+* @returns A sync value parser producing JavaScript {@link RegExp} objects.
+* @throws {TypeError} If `options.metavar` is an empty string or
+*   `options.flags` is not a string.
+* @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+*   incompatible regular expression flags.
+* @since 1.3.0
+*/
+function regExp(options = {}) {
+	const metavar$1 = options.metavar ?? "REGEXP";
+	ensureNonEmptyString(metavar$1);
+	if (options.flags !== void 0 && typeof options.flags !== "string") throw new TypeError(`Expected flags to be a string, but got ${typeof options.flags}: ${String(options.flags)}.`);
+	const flags = new RegExp("", options.flags ?? "").flags;
+	const invalidRegExp = options.errors?.invalidRegExp;
+	const parseRegExp = (input) => {
+		try {
+			return {
+				success: true,
+				value: new RegExp(input, flags)
+			};
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+			return {
+				success: false,
+				error: invalidRegExp ? typeof invalidRegExp === "function" ? invalidRegExp(input) : invalidRegExp : message`Invalid regular expression: ${input}.`
+			};
+		}
+	};
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new RegExp("", flags);
+		},
+		parse: parseRegExp,
+		validate(value) {
+			if (!(value instanceof RegExp)) return {
+				success: false,
+				error: message`Expected a RegExp value.`
+			};
+			return parseRegExp(value.source);
+		},
+		normalize(value) {
+			if (!(value instanceof RegExp)) return value;
+			const result = parseRegExp(value.source);
+			return result.success ? result.value : value;
+		},
+		format(value) {
+			return value.source;
+		}
+	};
+}
 function keyValue(options = {}) {
 	const separator = options.separator ?? "=";
 	if (typeof separator !== "string") throw new TypeError(`Expected separator to be a string, but got ${typeof separator}: ${String(separator)}.`);
@@ -6602,4 +6667,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, transform, url, uuid };
+export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2366",
+  "version": "1.3.0-dev.2375",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2366+c83510d8",
+    "@optique/env": "1.3.0-dev.2375+820d01c0",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -40,11 +40,12 @@ Core rules
  -  Use `message` from *@optique/core/message* for descriptions, help text, and
     custom errors. Prefer semantic message helpers such as `optionName()` and
     `metavar()` over string concatenation when naming CLI elements.
- -  Use value parsers such as `integer()`, `choice()`, `biject()`, `url()`,
-    and `uuid()` instead of validating raw strings after parsing. Use
-    `biject()` for one-to-one string-to-value choices, and use `transform()`
-    when an existing value parser describes the accepted CLI spelling but your
-    app needs a different result type. Use `path()` from
+ -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
+    `url()`, and `uuid()` instead of validating raw strings after parsing. Use
+    `regExp({ flags })` for user-supplied regular expression sources,
+    `biject()` for one-to-one string-to-value choices, and `transform()` when
+    an existing value parser describes the accepted CLI spelling but your app
+    needs a different result type. Use `path()` from
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.