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

package/dist/primitives.js

@@ -0,0 +1,591 @@
+import { message, metavar, optionName, optionNames } from "./message.js";
+import { isValueParser } from "./valueparser.js";
+
+//#region src/primitives.ts
+/**
+* Creates a parser that always succeeds without consuming any input and
+* produces a constant value of the type {@link T}.
+* @template T The type of the constant value produced by the parser.
+*/
+function constant(value) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 0,
+		usage: [],
+		initialState: value,
+		parse(context) {
+			return {
+				success: true,
+				next: context,
+				consumed: []
+			};
+		},
+		complete(state) {
+			return {
+				success: true,
+				value: state
+			};
+		},
+		getDocFragments(_state, _defaultValue) {
+			return { fragments: [] };
+		}
+	};
+}
+function option(...args) {
+	const lastArg = args.at(-1);
+	const secondLastArg = args.at(-2);
+	let valueParser;
+	let optionNames$1;
+	let options = {};
+	if (isValueParser(lastArg)) {
+		valueParser = lastArg;
+		optionNames$1 = args.slice(0, -1);
+	} else if (typeof lastArg === "object" && lastArg != null) {
+		options = lastArg;
+		if (isValueParser(secondLastArg)) {
+			valueParser = secondLastArg;
+			optionNames$1 = args.slice(0, -2);
+		} else {
+			valueParser = void 0;
+			optionNames$1 = args.slice(0, -1);
+		}
+	} else {
+		optionNames$1 = args;
+		valueParser = void 0;
+	}
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 10,
+		usage: [valueParser == null ? {
+			type: "optional",
+			terms: [{
+				type: "option",
+				names: optionNames$1
+			}]
+		} : {
+			type: "option",
+			names: optionNames$1,
+			metavar: valueParser.metavar
+		}],
+		initialState: valueParser == null ? {
+			success: true,
+			value: false
+		} : {
+			success: false,
+			error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Missing option ${optionNames(optionNames$1)}.`
+		},
+		parse(context) {
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.optionsTerminated ?? message`No more options can be parsed.`
+			};
+			else if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.endOfInput ?? message`Expected an option, but got end of input.`
+			};
+			if (context.buffer[0] === "--") return {
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(1),
+					state: context.state,
+					optionsTerminated: true
+				},
+				consumed: context.buffer.slice(0, 1)
+			};
+			if (optionNames$1.includes(context.buffer[0])) {
+				if (context.state.success && (valueParser != null || context.state.value)) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(context.buffer[0]) : options.errors.duplicate : message`${context.buffer[0]} cannot be used multiple times.`
+				};
+				if (valueParser == null) return {
+					success: true,
+					next: {
+						...context,
+						state: {
+							success: true,
+							value: true
+						},
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+				if (context.buffer.length < 2) return {
+					success: false,
+					consumed: 1,
+					error: message`Option ${optionName(context.buffer[0])} requires a value, but got no value.`
+				};
+				const result = valueParser.parse(context.buffer[1]);
+				return {
+					success: true,
+					next: {
+						...context,
+						state: result,
+						buffer: context.buffer.slice(2)
+					},
+					consumed: context.buffer.slice(0, 2)
+				};
+			}
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			for (const prefix of prefixes) {
+				if (!context.buffer[0].startsWith(prefix)) continue;
+				if (context.state.success && (valueParser != null || context.state.value)) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(prefix) : options.errors.duplicate : message`${optionName(prefix)} cannot be used multiple times.`
+				};
+				const value = context.buffer[0].slice(prefix.length);
+				if (valueParser == null) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(value) : options.errors.unexpectedValue : message`Option ${optionName(prefix)} is a Boolean flag, but got a value: ${value}.`
+				};
+				const result = valueParser.parse(value);
+				return {
+					success: true,
+					next: {
+						...context,
+						state: result,
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+			}
+			if (valueParser == null) {
+				const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
+				for (const shortOption of shortOptions) {
+					if (!context.buffer[0].startsWith(shortOption)) continue;
+					if (context.state.success && (valueParser != null || context.state.value)) return {
+						success: false,
+						consumed: 1,
+						error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(shortOption) : options.errors.duplicate : message`${optionName(shortOption)} cannot be used multiple times.`
+					};
+					return {
+						success: true,
+						next: {
+							...context,
+							state: {
+								success: true,
+								value: true
+							},
+							buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
+						},
+						consumed: [context.buffer[0].slice(0, 2)]
+					};
+				}
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: message`No matched option for ${optionName(context.buffer[0])}.`
+			};
+		},
+		complete(state) {
+			if (state == null) return valueParser == null ? {
+				success: true,
+				value: false
+			} : {
+				success: false,
+				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Missing option ${optionNames(optionNames$1)}.`
+			};
+			if (state.success) return state;
+			return {
+				success: false,
+				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${optionNames(optionNames$1)}: ${state.error}`
+			};
+		},
+		getDocFragments(_state, defaultValue) {
+			const fragments = [{
+				type: "entry",
+				term: {
+					type: "option",
+					names: optionNames$1,
+					metavar: valueParser?.metavar
+				},
+				description: options.description,
+				default: defaultValue != null && valueParser != null ? message`${valueParser.format(defaultValue)}` : void 0
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `option(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
+		}
+	};
+}
+/**
+* Creates a parser for command-line flags that must be explicitly provided.
+* Unlike {@link option}, this parser fails if the flag is not present, making
+* it suitable for required boolean flags that don't have a meaningful default.
+*
+* The key difference from {@link option} is:
+* - {@link option} without a value parser: Returns `false` when not present
+* - {@link flag}: Fails parsing when not present, only produces `true`
+*
+* This is useful for dependent options where the presence of a flag changes
+* the shape of the result type.
+*
+* @param args The {@link OptionName}s to parse, followed by an optional
+*             {@link FlagOptions} object that allows you to specify
+*             a description or other metadata.
+* @returns A {@link Parser} that produces `true` when the flag is present
+*          and fails when it is not present.
+*
+* @example
+* ```typescript
+* // Basic flag usage
+* const parser = flag("-f", "--force");
+* // Succeeds with true: parse(parser, ["-f"])
+* // Fails: parse(parser, [])
+*
+* // With description
+* const verboseFlag = flag("-v", "--verbose", {
+*   description: "Enable verbose output"
+* });
+* ```
+*/
+function flag(...args) {
+	const lastArg = args.at(-1);
+	let optionNames$1;
+	let options = {};
+	if (typeof lastArg === "object" && lastArg != null && !Array.isArray(lastArg)) {
+		options = lastArg;
+		optionNames$1 = args.slice(0, -1);
+	} else optionNames$1 = args;
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 10,
+		usage: [{
+			type: "option",
+			names: optionNames$1
+		}],
+		initialState: void 0,
+		parse(context) {
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.optionsTerminated ?? message`No more options can be parsed.`
+			};
+			else if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.endOfInput ?? message`Expected an option, but got end of input.`
+			};
+			if (context.buffer[0] === "--") return {
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(1),
+					state: context.state,
+					optionsTerminated: true
+				},
+				consumed: context.buffer.slice(0, 1)
+			};
+			if (optionNames$1.includes(context.buffer[0])) {
+				if (context.state?.success) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(context.buffer[0]) : options.errors.duplicate : message`${optionName(context.buffer[0])} cannot be used multiple times.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						state: {
+							success: true,
+							value: true
+						},
+						buffer: context.buffer.slice(1)
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+			}
+			const prefixes = optionNames$1.filter((name) => name.startsWith("--") || name.startsWith("/")).map((name) => name.startsWith("/") ? `${name}:` : `${name}=`);
+			for (const prefix of prefixes) if (context.buffer[0].startsWith(prefix)) {
+				const value = context.buffer[0].slice(prefix.length);
+				return {
+					success: false,
+					consumed: 1,
+					error: message`Flag ${optionName(prefix.slice(0, -1))} does not accept a value, but got: ${value}.`
+				};
+			}
+			const shortOptions = optionNames$1.filter((name) => name.match(/^-[^-]$/));
+			for (const shortOption of shortOptions) {
+				if (!context.buffer[0].startsWith(shortOption)) continue;
+				if (context.state?.success) return {
+					success: false,
+					consumed: 1,
+					error: options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(shortOption) : options.errors.duplicate : message`${optionName(shortOption)} cannot be used multiple times.`
+				};
+				return {
+					success: true,
+					next: {
+						...context,
+						state: {
+							success: true,
+							value: true
+						},
+						buffer: [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)]
+					},
+					consumed: [context.buffer[0].slice(0, 2)]
+				};
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: message`No matched option for ${optionName(context.buffer[0])}.`
+			};
+		},
+		complete(state) {
+			if (state == null) return {
+				success: false,
+				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(optionNames$1) : options.errors.missing : message`Required flag ${optionNames(optionNames$1)} is missing.`
+			};
+			if (state.success) return {
+				success: true,
+				value: true
+			};
+			return {
+				success: false,
+				error: message`${optionNames(optionNames$1)}: ${state.error}`
+			};
+		},
+		getDocFragments(_state, _defaultValue) {
+			const fragments = [{
+				type: "entry",
+				term: {
+					type: "option",
+					names: optionNames$1
+				},
+				description: options.description
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `flag(${optionNames$1.map((o) => JSON.stringify(o)).join(", ")})`;
+		}
+	};
+}
+/**
+* Creates a parser that expects a single argument value.
+* This parser is typically used for positional arguments
+* that are not options or flags.
+* @template T The type of the value produced by the parser.
+* @param valueParser The {@link ValueParser} that defines how to parse
+*                    the argument value.
+* @param options Optional configuration for the argument parser,
+*                allowing you to specify a description or other metadata.
+* @returns A {@link Parser} that expects a single argument value and produces
+*          the parsed value of type {@link T}.
+*/
+function argument(valueParser, options = {}) {
+	const optionPattern = /^--?[a-z0-9-]+$/i;
+	const term = {
+		type: "argument",
+		metavar: valueParser.metavar
+	};
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 5,
+		usage: [term],
+		initialState: void 0,
+		parse(context) {
+			if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.endOfInput ?? message`Expected an argument, but got end of input.`
+			};
+			let i = 0;
+			let optionsTerminated = context.optionsTerminated;
+			if (!optionsTerminated) {
+				if (context.buffer[i] === "--") {
+					optionsTerminated = true;
+					i++;
+				} else if (context.buffer[i].match(optionPattern)) return {
+					success: false,
+					consumed: i,
+					error: message`Expected an argument, but got an option: ${optionName(context.buffer[i])}.`
+				};
+			}
+			if (context.buffer.length < i + 1) return {
+				success: false,
+				consumed: i,
+				error: message`Expected an argument, but got end of input.`
+			};
+			if (context.state != null) return {
+				success: false,
+				consumed: i,
+				error: options.errors?.multiple ? typeof options.errors.multiple === "function" ? options.errors.multiple(valueParser.metavar) : options.errors.multiple : message`The argument ${metavar(valueParser.metavar)} cannot be used multiple times.`
+			};
+			const result = valueParser.parse(context.buffer[i]);
+			return {
+				success: true,
+				next: {
+					...context,
+					buffer: context.buffer.slice(i + 1),
+					state: result,
+					optionsTerminated
+				},
+				consumed: context.buffer.slice(0, i + 1)
+			};
+		},
+		complete(state) {
+			if (state == null) return {
+				success: false,
+				error: options.errors?.endOfInput ?? message`Expected a ${metavar(valueParser.metavar)}, but too few arguments.`
+			};
+			else if (state.success) return state;
+			return {
+				success: false,
+				error: options.errors?.invalidValue ? typeof options.errors.invalidValue === "function" ? options.errors.invalidValue(state.error) : options.errors.invalidValue : message`${metavar(valueParser.metavar)}: ${state.error}`
+			};
+		},
+		getDocFragments(_state, defaultValue) {
+			const fragments = [{
+				type: "entry",
+				term,
+				description: options.description,
+				default: defaultValue == null ? void 0 : message`${valueParser.format(defaultValue)}`
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `argument()`;
+		}
+	};
+}
+/**
+* Creates a parser that matches a specific subcommand name and then applies
+* an inner parser to the remaining arguments.
+* This is useful for building CLI tools with subcommands like git, npm, etc.
+* @template T The type of the value returned by the inner parser.
+* @template TState The type of the state used by the inner parser.
+* @param name The subcommand name to match (e.g., `"show"`, `"edit"`).
+* @param parser The {@link Parser} to apply after the command is matched.
+* @param options Optional configuration for the command parser, such as
+*                a description for documentation.
+* @returns A {@link Parser} that matches the command name and delegates
+*          to the inner parser for the remaining arguments.
+*/
+function command(name, parser, options = {}) {
+	return {
+		$valueType: [],
+		$stateType: [],
+		priority: 15,
+		usage: [{
+			type: "command",
+			name
+		}, ...parser.usage],
+		initialState: void 0,
+		parse(context) {
+			if (context.state === void 0) {
+				if (context.buffer.length < 1 || context.buffer[0] !== name) {
+					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
+					const errorMessage = options.errors?.notMatched ?? message`Expected command ${optionName(name)}, but got ${actual ?? "end of input"}.`;
+					return {
+						success: false,
+						consumed: 0,
+						error: typeof errorMessage === "function" ? errorMessage(name, actual) : errorMessage
+					};
+				}
+				return {
+					success: true,
+					next: {
+						...context,
+						buffer: context.buffer.slice(1),
+						state: ["matched", name]
+					},
+					consumed: context.buffer.slice(0, 1)
+				};
+			} else if (context.state[0] === "matched") {
+				const result = parser.parse({
+					...context,
+					state: parser.initialState
+				});
+				if (result.success) return {
+					success: true,
+					next: {
+						...result.next,
+						state: ["parsing", result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return result;
+			} else if (context.state[0] === "parsing") {
+				const result = parser.parse({
+					...context,
+					state: context.state[1]
+				});
+				if (result.success) return {
+					success: true,
+					next: {
+						...result.next,
+						state: ["parsing", result.next.state]
+					},
+					consumed: result.consumed
+				};
+				return result;
+			}
+			return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.invalidState ?? message`Invalid command state.`
+			};
+		},
+		complete(state) {
+			if (typeof state === "undefined") return {
+				success: false,
+				error: options.errors?.notFound ?? message`Command ${optionName(name)} was not matched.`
+			};
+			else if (state[0] === "matched") return parser.complete(parser.initialState);
+			else if (state[0] === "parsing") return parser.complete(state[1]);
+			return {
+				success: false,
+				error: options.errors?.invalidState ?? message`Invalid command state during completion.`
+			};
+		},
+		getDocFragments(state, defaultValue) {
+			if (state.kind === "unavailable" || typeof state.state === "undefined") return {
+				description: options.description,
+				fragments: [{
+					type: "entry",
+					term: {
+						type: "command",
+						name
+					},
+					description: options.description
+				}]
+			};
+			const innerState = state.state[0] === "parsing" ? {
+				kind: "available",
+				state: state.state[1]
+			} : { kind: "unavailable" };
+			const innerFragments = parser.getDocFragments(innerState, defaultValue);
+			return {
+				...innerFragments,
+				description: innerFragments.description ?? options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			return `command(${JSON.stringify(name)})`;
+		}
+	};
+}
+
+//#endregion
+export { argument, command, constant, flag, option };