@optique/core 0.1.0-dev.1

package/dist/usage.js

@@ -0,0 +1,239 @@
+//#region src/usage.ts
+/**
+* Formats a usage description into a human-readable string representation
+* suitable for command-line help text.
+*
+* This function converts a structured {@link Usage} description into a
+* formatted string that follows common CLI conventions. It supports various
+* formatting options including colors and compact option display.
+* @param programName The name of the program or command for which the usage
+*                    description is being formatted. This is typically the
+*                    name of the executable or script that the user will run.
+* @param usage The usage description to format, consisting of an array
+*              of usage terms representing the command-line structure.
+* @param options Optional formatting options to customize the output.
+*                See {@link UsageFormatOptions} for available options.
+* @returns A formatted string representation of the usage description.
+*/
+function formatUsage(programName, usage, options = {}) {
+	usage = normalizeUsage(usage);
+	if (options.expandCommands) {
+		const lastTerm = usage.at(-1);
+		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
+			const lines = [];
+			for (let command of lastTerm.terms) {
+				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
+				lines.push(formatUsage(programName, command, options));
+			}
+			return lines.join("\n");
+		}
+	}
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
+	let lineWidth = programName.length + 1;
+	for (const { text, width } of formatUsageTerms(usage, options)) {
+		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			output += "\n";
+			lineWidth = 0;
+			if (text === " ") continue;
+		}
+		output += text;
+		lineWidth += width;
+	}
+	return output;
+}
+/**
+* Normalizes a usage description by flattening nested exclusive terms,
+* sorting terms for better readability, and ensuring consistent structure
+* throughout the usage tree.
+*
+* This function performs two main operations:
+*
+* 1. *Flattening*: Recursively processes all usage terms and merges any
+*    nested exclusive terms into their parent exclusive term to avoid
+*    redundant nesting. For example, an exclusive term containing another
+*    exclusive term will have its nested terms flattened into the parent.
+*
+* 2. *Sorting*: Reorders terms to improve readability by placing:
+*    - Commands (subcommands) first
+*    - Options and other terms in the middle
+*    - Positional arguments last (including optional/multiple wrappers around
+*      arguments)
+*
+* The sorting logic also recognizes when optional or multiple terms contain
+* positional arguments and treats them as arguments for sorting purposes.
+*
+* @param usage The usage description to normalize.
+* @returns A normalized usage description with flattened exclusive terms
+*          and terms sorted for optimal readability.
+*/
+function normalizeUsage(usage) {
+	const terms = usage.map(normalizeUsageTerm);
+	terms.sort((a, b) => {
+		const aCmd = a.type === "command";
+		const bCmd = b.type === "command";
+		const aArg = a.type === "argument" || (a.type === "optional" || a.type === "multiple") && a.terms.at(-1)?.type === "argument";
+		const bArg = b.type === "argument" || (b.type === "optional" || b.type === "multiple") && b.terms.at(-1)?.type === "argument";
+		return aCmd === bCmd ? aArg === bArg ? 0 : aArg ? 1 : -1 : aCmd ? -1 : 1;
+	});
+	return terms;
+}
+function normalizeUsageTerm(term) {
+	if (term.type === "optional") return {
+		type: "optional",
+		terms: normalizeUsage(term.terms)
+	};
+	else if (term.type === "multiple") return {
+		type: "multiple",
+		terms: normalizeUsage(term.terms),
+		min: term.min
+	};
+	else if (term.type === "exclusive") {
+		const terms = [];
+		for (const usage of term.terms) {
+			const normalized = normalizeUsage(usage);
+			if (normalized.length === 1 && normalized[0].type === "exclusive") for (const subUsage of normalized[0].terms) terms.push(subUsage);
+			else terms.push(normalized);
+		}
+		return {
+			type: "exclusive",
+			terms
+		};
+	} else return term;
+}
+function* formatUsageTerms(terms, options) {
+	let i = 0;
+	for (const t of terms) {
+		if (i > 0) yield {
+			text: " ",
+			width: 1
+		};
+		yield* formatUsageTermInternal(t, options);
+		i++;
+	}
+}
+/**
+* Formats a single {@link UsageTerm} into a string representation
+* suitable for command-line help text.
+* @param term The usage term to format, which can be an argument,
+*             option, command, optional term, exclusive term, or multiple term.
+* @param options Optional formatting options to customize the output.
+*                See {@link UsageTermFormatOptions} for available options.
+* @returns A formatted string representation of the usage term.
+*/
+function formatUsageTerm(term, options = {}) {
+	let lineWidth = 0;
+	let output = "";
+	for (const { text, width } of formatUsageTermInternal(term, options)) {
+		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			output += "\n";
+			lineWidth = 0;
+			if (text === " ") continue;
+		}
+		output += text;
+		lineWidth += width;
+	}
+	return output;
+}
+function* formatUsageTermInternal(term, options) {
+	const optionsSeparator = options.optionsSeparator ?? "/";
+	if (term.type === "argument") yield {
+		text: options?.colors ? `\x1b[4m${term.metavar}\x1b[0m` : term.metavar,
+		width: term.metavar.length
+	};
+	else if (term.type === "option") if (options?.onlyShortestOptions) {
+		const shortestName = term.names.reduce((a, b) => a.length <= b.length ? a : b);
+		yield {
+			text: options?.colors ? `\x1b[3m${shortestName}\x1b[0m` : shortestName,
+			width: shortestName.length
+		};
+	} else {
+		let i = 0;
+		for (const optionName of term.names) {
+			if (i > 0) yield {
+				text: options?.colors ? `\x1b[2m${optionsSeparator}\x1b[0m` : optionsSeparator,
+				width: optionsSeparator.length
+			};
+			yield {
+				text: options?.colors ? `\x1b[3m${optionName}\x1b[0m` : optionName,
+				width: optionName.length
+			};
+			i++;
+		}
+		if (term.metavar != null) {
+			yield {
+				text: " ",
+				width: 1
+			};
+			yield {
+				text: options?.colors ? `\x1b[4m\x1b[2m${term.metavar}\x1b[0m` : term.metavar,
+				width: term.metavar.length
+			};
+		}
+	}
+	else if (term.type === "command") yield {
+		text: options?.colors ? `\x1b[1m${term.name}\x1b[0m` : term.name,
+		width: term.name.length
+	};
+	else if (term.type === "optional") {
+		yield {
+			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
+			width: 1
+		};
+		yield* formatUsageTerms(term.terms, options);
+		yield {
+			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
+			width: 1
+		};
+	} else if (term.type === "exclusive") {
+		yield {
+			text: options?.colors ? `\x1b[2m(\x1b[0m` : "(",
+			width: 1
+		};
+		let i = 0;
+		for (const termGroup of term.terms) {
+			if (i > 0) {
+				yield {
+					text: " ",
+					width: 1
+				};
+				yield {
+					text: "|",
+					width: 1
+				};
+				yield {
+					text: " ",
+					width: 1
+				};
+			}
+			yield* formatUsageTerms(termGroup, options);
+			i++;
+		}
+		yield {
+			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
+			width: 1
+		};
+	} else if (term.type === "multiple") {
+		if (term.min < 1) yield {
+			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
+			width: 1
+		};
+		for (let i = 0; i < Math.max(1, term.min); i++) {
+			if (i > 0) yield {
+				text: " ",
+				width: 1
+			};
+			yield* formatUsageTerms(term.terms, options);
+		}
+		yield {
+			text: options?.colors ? `\x1b[2m...\x1b[0m` : "...",
+			width: 3
+		};
+		if (term.min < 1) yield {
+			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
+			width: 1
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+}
+
+//#endregion
+export { formatUsage, formatUsageTerm, normalizeUsage };

package/dist/valueparser.cjs

@@ -0,0 +1,332 @@
+const require_message = require('./message.cjs');
+
+//#region src/valueparser.ts
+/**
+* A predicate function that checks if an object is a {@link ValueParser}.
+* @param object The object to check.
+* @return `true` if the object is a {@link ValueParser}, `false` otherwise.
+*/
+function isValueParser(object) {
+	return typeof object === "object" && object != null && "metavar" in object && typeof object.metavar === "string" && "parse" in object && typeof object.parse === "function" && "format" in object && typeof object.format === "function";
+}
+/**
+* Creates a {@link ValueParser} that accepts one of multiple
+* string values, so-called enumerated values.
+*
+* This parser validates that the input string matches one of
+* the specified values. If the input does not match any of the values,
+* it returns an error message indicating the valid options.
+* @param values An array of valid string values that this parser can accept.
+* @param options Configuration options for the choice parser.
+* @returns A {@link ValueParser} that checks if the input matches one of the
+*          specified values.
+*/
+function choice(values, options = {}) {
+	const normalizedValues = options.caseInsensitive ? values.map((v) => v.toLowerCase()) : values;
+	return {
+		metavar: options.metavar ?? "TYPE",
+		parse(input) {
+			const normalizedInput = options.caseInsensitive ? input.toLowerCase() : input;
+			const index = normalizedValues.indexOf(normalizedInput);
+			if (index < 0) return {
+				success: false,
+				error: require_message.message`Expected one of ${values.join(", ")}, but got ${input}.`
+			};
+			return {
+				success: true,
+				value: values[index]
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+/**
+* Creates a {@link ValueParser} for strings.
+*
+* This parser validates that the input is a string and optionally checks
+* if it matches a specified regular expression pattern.
+* @param options Configuration options for the string parser.
+* @returns A {@link ValueParser} that parses strings according to the
+*          specified options.
+*/
+function string(options = {}) {
+	return {
+		metavar: options.metavar ?? "STRING",
+		parse(input) {
+			if (options.pattern != null && !options.pattern.test(input)) return {
+				success: false,
+				error: require_message.message`Expected a string matching pattern ${require_message.text(options.pattern.source)}, but got ${input}.`
+			};
+			return {
+				success: true,
+				value: input
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+/**
+* Creates a ValueParser for parsing integer values from strings.
+*
+* This function provides two modes of operation:
+*
+* - Regular mode: Returns JavaScript numbers
+*   (safe up to `Number.MAX_SAFE_INTEGER`)
+* - `bigint` mode: Returns `bigint` values for arbitrarily large integers
+*
+* The parser validates that the input is a valid integer and optionally
+* enforces minimum and maximum value constraints.
+*
+* @example
+* ```typescript
+* // Create a parser for regular integers
+* const portParser = integer({ min: 1, max: 65535 });
+*
+* // Create a parser for BigInt values
+* const bigIntParser = integer({ type: "bigint", min: 0n });
+*
+* // Use the parser
+* const result = portParser.parse("8080");
+* if (result.success) {
+*   console.log(`Port: ${result.value}`);
+* } else {
+*   console.error(result.error);
+* }
+* ```
+*
+* @param options Configuration options specifying the type and constraints.
+* @returns A {@link ValueParser} that converts string input to the specified
+*          integer type.
+*/
+function integer(options) {
+	if (options?.type === "bigint") return {
+		metavar: options.metavar ?? "INTEGER",
+		parse(input) {
+			let value;
+			try {
+				value = BigInt(input);
+			} catch (e) {
+				if (e instanceof SyntaxError) return {
+					success: false,
+					error: require_message.message`Expected a valid integer, but got ${input}.`
+				};
+				throw e;
+			}
+			if (options.min != null && value < options.min) return {
+				success: false,
+				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+			};
+			else if (options.max != null && value > options.max) return {
+				success: false,
+				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+			};
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			return value.toString();
+		}
+	};
+	return {
+		metavar: options?.metavar ?? "INTEGER",
+		parse(input) {
+			if (!input.match(/^\d+$/)) return {
+				success: false,
+				error: require_message.message`Expected a valid integer, but got ${input}.`
+			};
+			const value = Number.parseInt(input);
+			if (options?.min != null && value < options.min) return {
+				success: false,
+				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+			};
+			else if (options?.max != null && value > options.max) return {
+				success: false,
+				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+			};
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			return value.toString();
+		}
+	};
+}
+/**
+* Creates a {@link ValueParser} for floating-point numbers.
+*
+* This parser validates that the input is a valid floating-point number
+* and optionally enforces minimum and maximum value constraints.
+* @param options Configuration options for the float parser.
+* @returns A {@link ValueParser} that parses strings into floating-point
+*          numbers.
+*/
+function float(options = {}) {
+	const floatRegex = /^[+-]?(?:(?:\d+\.?\d*)|(?:\d*\.\d+))(?:[eE][+-]?\d+)?$/;
+	return {
+		metavar: options.metavar ?? "NUMBER",
+		parse(input) {
+			let value;
+			const lowerInput = input.toLowerCase();
+			if (lowerInput === "nan" && options.allowNaN) value = NaN;
+			else if ((lowerInput === "infinity" || lowerInput === "+infinity") && options.allowInfinity) value = Infinity;
+			else if (lowerInput === "-infinity" && options.allowInfinity) value = -Infinity;
+			else if (floatRegex.test(input)) {
+				value = Number(input);
+				if (Number.isNaN(value)) return {
+					success: false,
+					error: require_message.message`Expected a valid number, but got ${input}.`
+				};
+			} else return {
+				success: false,
+				error: require_message.message`Expected a valid number, but got ${input}.`
+			};
+			if (options.min != null && value < options.min) return {
+				success: false,
+				error: require_message.message`Expected a value greater than or equal to ${require_message.text(options.min.toLocaleString("en"))}, but got ${input}.`
+			};
+			else if (options.max != null && value > options.max) return {
+				success: false,
+				error: require_message.message`Expected a value less than or equal to ${require_message.text(options.max.toLocaleString("en"))}, but got ${input}.`
+			};
+			return {
+				success: true,
+				value
+			};
+		},
+		format(value) {
+			return value.toString();
+		}
+	};
+}
+/**
+* Creates a {@link ValueParser} for URL values.
+*
+* This parser validates that the input is a well-formed URL and optionally
+* restricts the allowed protocols. The parsed result is a JavaScript `URL`
+* object.
+* @param options Configuration options for the URL parser.
+* @returns A {@link ValueParser} that converts string input to `URL` objects.
+*/
+function url(options = {}) {
+	const allowedProtocols = options.allowedProtocols?.map((p) => p.toLowerCase());
+	return {
+		metavar: options.metavar ?? "URL",
+		parse(input) {
+			if (!URL.canParse(input)) return {
+				success: false,
+				error: require_message.message`Invalid URL: ${input}.`
+			};
+			const url$1 = new URL(input);
+			if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
+				success: false,
+				error: require_message.message`URL protocol ${url$1.protocol} is not allowed. Allowed protocols: ${allowedProtocols.join(", ")}.`
+			};
+			return {
+				success: true,
+				value: url$1
+			};
+		},
+		format(value) {
+			return value.href;
+		}
+	};
+}
+/**
+* Creates a {@link ValueParser} for locale values.
+*
+* This parser validates that the input is a well-formed locale identifier
+* according to the Unicode Locale Identifier standard (BCP 47).
+* The parsed result is a JavaScript `Intl.Locale` object.
+* @param options Configuration options for the locale parser.
+* @returns A {@link ValueParser} that converts string input to `Intl.Locale`
+*          objects.
+*/
+function locale(options = {}) {
+	return {
+		metavar: options.metavar ?? "LOCALE",
+		parse(input) {
+			let locale$1;
+			try {
+				locale$1 = new Intl.Locale(input);
+			} catch (e) {
+				if (e instanceof RangeError) return {
+					success: false,
+					error: require_message.message`Invalid locale: ${input}.`
+				};
+				throw e;
+			}
+			return {
+				success: true,
+				value: locale$1
+			};
+		},
+		format(value) {
+			return value.baseName;
+		}
+	};
+}
+/**
+* Creates a {@link ValueParser} for UUID values.
+*
+* This parser validates that the input is a well-formed UUID string in the
+* standard format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx` where each `x`
+* is a hexadecimal digit.  The parser can optionally restrict to specific
+* UUID versions.
+*
+* @param options Configuration options for the UUID parser.
+* @returns A {@link ValueParser} that converts string input to {@link Uuid}
+*          strings.
+*/
+function uuid(options = {}) {
+	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+	return {
+		metavar: options.metavar ?? "UUID",
+		parse(input) {
+			if (!uuidRegex.test(input)) return {
+				success: false,
+				error: require_message.message`Expected a valid UUID in format ${"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"}, but got ${input}.`
+			};
+			if (options.allowedVersions != null && options.allowedVersions.length > 0) {
+				const versionChar = input.charAt(14);
+				const version = parseInt(versionChar, 16);
+				if (!options.allowedVersions.includes(version)) {
+					let expectedVersions = require_message.message``;
+					let i = 0;
+					for (const v of options.allowedVersions) {
+						expectedVersions = i < 1 ? require_message.message`${expectedVersions}${v.toLocaleString("en")}` : i + 1 >= options.allowedVersions.length ? require_message.message`${expectedVersions}, or ${v.toLocaleString("en")}` : require_message.message`${expectedVersions}, ${v.toLocaleString("en")}`;
+						i++;
+					}
+					return {
+						success: false,
+						error: require_message.message`Expected UUID version ${expectedVersions}, but got version ${version.toLocaleString("en")}.`
+					};
+				}
+			}
+			return {
+				success: true,
+				value: input
+			};
+		},
+		format(value) {
+			return value;
+		}
+	};
+}
+
+//#endregion
+exports.choice = choice;
+exports.float = float;
+exports.integer = integer;
+exports.isValueParser = isValueParser;
+exports.locale = locale;
+exports.string = string;
+exports.url = url;
+exports.uuid = uuid;