@optique/core 0.5.0-dev.79 → 0.5.0-dev.80

package/dist/facade.cjs

@@ -1,7 +1,10 @@
 const require_message = require('./message.cjs');
+const require_constructs = require('./constructs.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
+const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
+const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
 
 //#region src/facade.ts
@@ -9,16 +12,16 @@ const require_parser = require('./parser.cjs');
 * Creates help parsers based on the specified mode.
 */
 function createHelpParser(mode) {
-	const helpCommand = require_parser.command("help", require_parser.multiple(require_parser.argument(require_valueparser.string({ metavar: "COMMAND" }))), { description: require_message.message`Show help information.` });
-	const helpOption = require_parser.flag("--help", { description: require_message.message`Show help information.` });
-	const _contextualHelpParser = require_parser.object({
-		help: require_parser.constant(true),
-		version: require_parser.constant(false),
-		commands: require_parser.multiple(require_parser.argument(require_valueparser.string({
+	const helpCommand = require_primitives.command("help", require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "COMMAND" }))), { description: require_message.message`Show help information.` });
+	const helpOption = require_primitives.flag("--help", { description: require_message.message`Show help information.` });
+	const _contextualHelpParser = require_constructs.object({
+		help: require_primitives.constant(true),
+		version: require_primitives.constant(false),
+		commands: require_modifiers.multiple(require_primitives.argument(require_valueparser.string({
 			metavar: "COMMAND",
 			pattern: /^[^-].*$/
 		}))),
-		__help: require_parser.flag("--help")
+		__help: require_primitives.flag("--help")
 	});
 	switch (mode) {
 		case "command": return {
@@ -42,8 +45,8 @@ function createHelpParser(mode) {
 * Creates version parsers based on the specified mode.
 */
 function createVersionParser(mode) {
-	const versionCommand = require_parser.command("version", require_parser.object({}), { description: require_message.message`Show version information.` });
-	const versionOption = require_parser.flag("--version", { description: require_message.message`Show version information.` });
+	const versionCommand = require_primitives.command("version", require_constructs.object({}), { description: require_message.message`Show version information.` });
+	const versionOption = require_primitives.flag("--version", { description: require_message.message`Show version information.` });
 	switch (mode) {
 		case "command": return {
 			versionCommand,
@@ -191,26 +194,26 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers) {
 		};
 		parsers.push(lenientVersionParser);
 	}
-	if (versionParsers.versionCommand) parsers.push(require_parser.object({
-		help: require_parser.constant(false),
-		version: require_parser.constant(true),
+	if (versionParsers.versionCommand) parsers.push(require_constructs.object({
+		help: require_primitives.constant(false),
+		version: require_primitives.constant(true),
 		result: versionParsers.versionCommand,
-		helpFlag: helpParsers.helpOption ? require_parser.optional(helpParsers.helpOption) : require_parser.constant(false)
+		helpFlag: helpParsers.helpOption ? require_modifiers.optional(helpParsers.helpOption) : require_primitives.constant(false)
 	}));
-	if (helpParsers.helpCommand) parsers.push(require_parser.object({
-		help: require_parser.constant(true),
-		version: require_parser.constant(false),
+	if (helpParsers.helpCommand) parsers.push(require_constructs.object({
+		help: require_primitives.constant(true),
+		version: require_primitives.constant(false),
 		commands: helpParsers.helpCommand
 	}));
 	if (helpParsers.contextualHelpParser) parsers.push(helpParsers.contextualHelpParser);
-	parsers.push(require_parser.object({
-		help: require_parser.constant(false),
-		version: require_parser.constant(false),
+	parsers.push(require_constructs.object({
+		help: require_primitives.constant(false),
+		version: require_primitives.constant(false),
 		result: originalParser
 	}));
 	if (parsers.length === 1) return parsers[0];
-	else if (parsers.length === 2) return require_parser.longestMatch(parsers[0], parsers[1]);
-	else return require_parser.longestMatch(...parsers);
+	else if (parsers.length === 2) return require_constructs.longestMatch(parsers[0], parsers[1]);
+	else return require_constructs.longestMatch(...parsers);
 }
 /**
 * Classifies the parsing result into a discriminated union for cleaner handling.
@@ -320,17 +323,17 @@ function run(parser, programName, args, options = {}) {
 			if (helpAsCommand && versionAsCommand) {
 				const tempHelpParsers = createHelpParser(help);
 				const tempVersionParsers = createVersionParser(version);
-				if (tempHelpParsers.helpCommand && tempVersionParsers.versionCommand) helpGeneratorParser = require_parser.longestMatch(parser, tempHelpParsers.helpCommand, tempVersionParsers.versionCommand);
-				else if (tempHelpParsers.helpCommand) helpGeneratorParser = require_parser.longestMatch(parser, tempHelpParsers.helpCommand);
-				else if (tempVersionParsers.versionCommand) helpGeneratorParser = require_parser.longestMatch(parser, tempVersionParsers.versionCommand);
+				if (tempHelpParsers.helpCommand && tempVersionParsers.versionCommand) helpGeneratorParser = require_constructs.longestMatch(parser, tempHelpParsers.helpCommand, tempVersionParsers.versionCommand);
+				else if (tempHelpParsers.helpCommand) helpGeneratorParser = require_constructs.longestMatch(parser, tempHelpParsers.helpCommand);
+				else if (tempVersionParsers.versionCommand) helpGeneratorParser = require_constructs.longestMatch(parser, tempVersionParsers.versionCommand);
 				else helpGeneratorParser = parser;
 			} else if (helpAsCommand) {
 				const tempHelpParsers = createHelpParser(help);
-				if (tempHelpParsers.helpCommand) helpGeneratorParser = require_parser.longestMatch(parser, tempHelpParsers.helpCommand);
+				if (tempHelpParsers.helpCommand) helpGeneratorParser = require_constructs.longestMatch(parser, tempHelpParsers.helpCommand);
 				else helpGeneratorParser = parser;
 			} else if (versionAsCommand) {
 				const tempVersionParsers = createVersionParser(version);
-				if (tempVersionParsers.versionCommand) helpGeneratorParser = require_parser.longestMatch(parser, tempVersionParsers.versionCommand);
+				if (tempVersionParsers.versionCommand) helpGeneratorParser = require_constructs.longestMatch(parser, tempVersionParsers.versionCommand);
 				else helpGeneratorParser = parser;
 			} else helpGeneratorParser = parser;
 			const doc = require_parser.getDocPage(helpGeneratorParser, classified.commands);

package/dist/facade.js

@@ -1,8 +1,11 @@
 import { formatMessage, message } from "./message.js";
+import { longestMatch, object } from "./constructs.js";
 import { formatUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
+import { multiple, optional } from "./modifiers.js";
 import { string } from "./valueparser.js";
-import { argument, command, constant, flag, getDocPage, longestMatch, multiple, object, optional, parse } from "./parser.js";
+import { argument, command, constant, flag } from "./primitives.js";
+import { getDocPage, parse } from "./parser.js";
 
 //#region src/facade.ts
 /**

package/dist/index.cjs

@@ -1,49 +1,52 @@
 const require_message = require('./message.cjs');
+const require_constructs = require('./constructs.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
+const require_modifiers = require('./modifiers.cjs');
 const require_valueparser = require('./valueparser.cjs');
+const require_primitives = require('./primitives.cjs');
 const require_parser = require('./parser.cjs');
 const require_facade = require('./facade.cjs');
 
 exports.RunError = require_facade.RunError;
-exports.WithDefaultError = require_parser.WithDefaultError;
-exports.argument = require_parser.argument;
+exports.WithDefaultError = require_modifiers.WithDefaultError;
+exports.argument = require_primitives.argument;
 exports.choice = require_valueparser.choice;
-exports.command = require_parser.command;
-exports.concat = require_parser.concat;
-exports.constant = require_parser.constant;
+exports.command = require_primitives.command;
+exports.concat = require_constructs.concat;
+exports.constant = require_primitives.constant;
 exports.envVar = require_message.envVar;
-exports.flag = require_parser.flag;
+exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;
 exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
 exports.getDocPage = require_parser.getDocPage;
-exports.group = require_parser.group;
+exports.group = require_constructs.group;
 exports.integer = require_valueparser.integer;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.locale = require_valueparser.locale;
-exports.longestMatch = require_parser.longestMatch;
-exports.map = require_parser.map;
-exports.merge = require_parser.merge;
+exports.longestMatch = require_constructs.longestMatch;
+exports.map = require_modifiers.map;
+exports.merge = require_constructs.merge;
 exports.message = require_message.message;
 exports.metavar = require_message.metavar;
-exports.multiple = require_parser.multiple;
+exports.multiple = require_modifiers.multiple;
 exports.normalizeUsage = require_usage.normalizeUsage;
-exports.object = require_parser.object;
-exports.option = require_parser.option;
+exports.object = require_constructs.object;
+exports.option = require_primitives.option;
 exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
-exports.optional = require_parser.optional;
-exports.or = require_parser.or;
+exports.optional = require_modifiers.optional;
+exports.or = require_constructs.or;
 exports.parse = require_parser.parse;
 exports.run = require_facade.run;
 exports.string = require_valueparser.string;
 exports.text = require_message.text;
-exports.tuple = require_parser.tuple;
+exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;
 exports.uuid = require_valueparser.uuid;
 exports.value = require_message.value;
 exports.values = require_message.values;
-exports.withDefault = require_parser.withDefault;
+exports.withDefault = require_modifiers.withDefault;

package/dist/index.d.cts

@@ -2,6 +2,9 @@ import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, mess
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
-import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.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 { DocState, InferValue, Parser, ParserContext, ParserResult, Result, getDocPage, parse } from "./parser.cjs";
+import { LongestMatchErrorOptions, LongestMatchOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.d.ts

@@ -2,6 +2,9 @@ import { Message, MessageFormatOptions, MessageTerm, envVar, formatMessage, mess
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowDefaultOptions, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, WithDefaultError, WithDefaultOptions, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.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 { DocState, InferValue, Parser, ParserContext, ParserResult, Result, getDocPage, parse } from "./parser.js";
+import { LongestMatchErrorOptions, LongestMatchOptions, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, CommandErrorOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, FlagErrorOptions, FlagOptions, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, Message, MessageFormatOptions, MessageTerm, MultipleErrorOptions, MultipleOptions, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OrErrorOptions, OrOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, ShowDefaultOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, WithDefaultError, WithDefaultOptions, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.js

@@ -1,8 +1,11 @@
 import { envVar, formatMessage, message, metavar, optionName, optionNames, text, value, values } from "./message.js";
+import { concat, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
+import { WithDefaultError, map, multiple, optional, withDefault } from "./modifiers.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { WithDefaultError, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { argument, command, constant, flag, option } from "./primitives.js";
+import { getDocPage, parse } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
 export { RunError, WithDefaultError, argument, choice, command, concat, constant, envVar, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, group, integer, isValueParser, locale, longestMatch, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/modifiers.cjs

@@ -0,0 +1,300 @@
+const require_message = require('./message.cjs');
+
+//#region src/modifiers.ts
+/**
+* Creates a parser that makes another parser optional, allowing it to succeed
+* without consuming input if the wrapped parser fails to match.
+* If the wrapped parser succeeds, this returns its value.
+* If the wrapped parser fails, this returns `undefined` without consuming input.
+* @template TValue The type of the value returned by the wrapped parser.
+* @template TState The type of the state used by the wrapped parser.
+* @param parser The {@link Parser} to make optional.
+* @returns A {@link Parser} that produces either the result of the wrapped parser
+*          or `undefined` if the wrapped parser fails to match.
+*/
+function optional(parser) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: void 0,
+		parse(context) {
+			const result = parser.parse({
+				...context,
+				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+			});
+			if (result.success) return {
+				success: true,
+				next: {
+					...result.next,
+					state: [result.next.state]
+				},
+				consumed: result.consumed
+			};
+			return result;
+		},
+		complete(state) {
+			if (typeof state === "undefined") return {
+				success: true,
+				value: void 0
+			};
+			return parser.complete(state[0]);
+		},
+		getDocFragments(state, defaultValue) {
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			return parser.getDocFragments(innerState, defaultValue);
+		}
+	};
+}
+/**
+* Error type for structured error messages in {@link withDefault} default value callbacks.
+* Unlike regular errors that only support string messages, this error type accepts
+* a {@link Message} object that supports rich formatting, colors, and structured content.
+*
+* @example
+* ```typescript
+* withDefault(option("--url", url()), () => {
+*   if (!process.env.INSTANCE_URL) {
+*     throw new WithDefaultError(
+*       message`Environment variable ${envVar("INSTANCE_URL")} is not set.`
+*     );
+*   }
+*   return new URL(process.env.INSTANCE_URL);
+* })
+* ```
+*
+* @since 0.5.0
+*/
+var WithDefaultError = class extends Error {
+	/**
+	* The structured message associated with this error.
+	*/
+	errorMessage;
+	/**
+	* Creates a new WithDefaultError with a structured message.
+	* @param message The structured {@link Message} describing the error.
+	*/
+	constructor(message$1) {
+		super(require_message.formatMessage(message$1));
+		this.errorMessage = message$1;
+		this.name = "WithDefaultError";
+	}
+};
+function withDefault(parser, defaultValue, options) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: void 0,
+		parse(context) {
+			const result = parser.parse({
+				...context,
+				state: typeof context.state === "undefined" ? parser.initialState : context.state[0]
+			});
+			if (result.success) return {
+				success: true,
+				next: {
+					...result.next,
+					state: [result.next.state]
+				},
+				consumed: result.consumed
+			};
+			return result;
+		},
+		complete(state) {
+			if (typeof state === "undefined") try {
+				const value = typeof defaultValue === "function" ? defaultValue() : defaultValue;
+				return {
+					success: true,
+					value
+				};
+			} catch (error) {
+				return {
+					success: false,
+					error: error instanceof WithDefaultError ? error.errorMessage : require_message.message`${require_message.text(String(error))}`
+				};
+			}
+			return parser.complete(state[0]);
+		},
+		getDocFragments(state, upperDefaultValue) {
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state === void 0 ? { kind: "unavailable" } : {
+				kind: "available",
+				state: state.state[0]
+			};
+			const actualDefaultValue = upperDefaultValue != null ? upperDefaultValue : typeof defaultValue === "function" ? defaultValue() : defaultValue;
+			const fragments = parser.getDocFragments(innerState, actualDefaultValue);
+			if (options?.message) {
+				const modifiedFragments = fragments.fragments.map((fragment) => {
+					if (fragment.type === "entry") return {
+						...fragment,
+						default: options.message
+					};
+					return fragment;
+				});
+				return {
+					...fragments,
+					fragments: modifiedFragments
+				};
+			}
+			return fragments;
+		}
+	};
+}
+/**
+* Creates a parser that transforms the result value of another parser using
+* a mapping function. This enables value transformation while preserving
+* the original parser's parsing logic and state management.
+*
+* The `map()` function is useful for:
+* - Converting parsed values to different types
+* - Applying transformations like string formatting or boolean inversion
+* - Computing derived values from parsed input
+* - Creating reusable transformations that can be applied to any parser
+*
+* @template T The type of the value produced by the original parser.
+* @template U The type of the value produced by the mapping function.
+* @template TState The type of the state used by the original parser.
+* @param parser The {@link Parser} whose result will be transformed.
+* @param transform A function that transforms the parsed value from type T to type U.
+* @returns A {@link Parser} that produces the transformed value of type U
+*          while preserving the original parser's state type and parsing behavior.
+*
+* @example
+* ```typescript
+* // Transform boolean flag to its inverse
+* const parser = object({
+*   disallow: map(option("--allow"), b => !b)
+* });
+*
+* // Transform string to uppercase
+* const upperParser = map(argument(string()), s => s.toUpperCase());
+*
+* // Transform number to formatted string
+* const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
+* ```
+*/
+function map(parser, transform) {
+	return {
+		$valueType: [],
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: parser.usage,
+		initialState: parser.initialState,
+		parse: parser.parse.bind(parser),
+		complete(state) {
+			const result = parser.complete(state);
+			if (result.success) return {
+				success: true,
+				value: transform(result.value)
+			};
+			return result;
+		},
+		getDocFragments(state, _defaultValue) {
+			return parser.getDocFragments(state, void 0);
+		}
+	};
+}
+/**
+* Creates a parser that allows multiple occurrences of a given parser.
+* This parser can be used to parse multiple values of the same type,
+* such as multiple command-line arguments or options.
+* @template TValue The type of the value that the parser produces.
+* @template TState The type of the state used by the parser.
+* @param parser The {@link Parser} to apply multiple times.
+* @param options Optional configuration for the parser,
+*                allowing you to specify the minimum and maximum number of
+*                occurrences allowed.
+* @returns A {@link Parser} that produces an array of values
+*          of type {@link TValue} and an array of states
+*          of type {@link TState}.
+*/
+function multiple(parser, options = {}) {
+	const { min = 0, max = Infinity } = options;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: parser.priority,
+		usage: [{
+			type: "multiple",
+			terms: parser.usage,
+			min
+		}],
+		initialState: [],
+		parse(context) {
+			let added = context.state.length < 1;
+			let result = parser.parse({
+				...context,
+				state: context.state.at(-1) ?? parser.initialState
+			});
+			if (!result.success) if (!added) {
+				result = parser.parse({
+					...context,
+					state: parser.initialState
+				});
+				if (!result.success) return result;
+				added = true;
+			} else return result;
+			return {
+				success: true,
+				next: {
+					...result.next,
+					state: [...added ? context.state : context.state.slice(0, -1), result.next.state]
+				},
+				consumed: result.consumed
+			};
+		},
+		complete(state) {
+			const result = [];
+			for (const s of state) {
+				const valueResult = parser.complete(s);
+				if (valueResult.success) result.push(valueResult.value);
+				else return {
+					success: false,
+					error: valueResult.error
+				};
+			}
+			if (result.length < min) {
+				const customMessage = options.errors?.tooFew;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(min, result.length) : customMessage : require_message.message`Expected at least ${require_message.text(min.toLocaleString("en"))} values, but got only ${require_message.text(result.length.toLocaleString("en"))}.`
+				};
+			} else if (result.length > max) {
+				const customMessage = options.errors?.tooMany;
+				return {
+					success: false,
+					error: customMessage ? typeof customMessage === "function" ? customMessage(max, result.length) : customMessage : require_message.message`Expected at most ${require_message.text(max.toLocaleString("en"))} values, but got ${require_message.text(result.length.toLocaleString("en"))}.`
+				};
+			}
+			return {
+				success: true,
+				value: result
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			const innerState = state.kind === "unavailable" ? { kind: "unavailable" } : state.state.length > 0 ? {
+				kind: "available",
+				state: state.state.at(-1)
+			} : { kind: "unavailable" };
+			return parser.getDocFragments(innerState, defaultValue != null && defaultValue.length > 0 ? defaultValue[0] : void 0);
+		}
+	};
+}
+
+//#endregion
+exports.WithDefaultError = WithDefaultError;
+exports.map = map;
+exports.multiple = multiple;
+exports.optional = optional;
+exports.withDefault = withDefault;