@optique/core 1.1.0-dev.1998 → 1.1.0-dev.2053

package/dist/primitives.cjs

@@ -260,7 +260,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 		}
 	} else {
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
-		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) {
+		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
@@ -274,7 +274,7 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) yield* getSuggestionsWithDependency(valueParser, prefix, context.dependencyRegistry, context.exec);
 		}
 	}
@@ -344,7 +344,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 		}
 	} else {
 		const expectingValue = context.buffer.length > 0 && optionNames$1.includes(context.buffer[context.buffer.length - 1]);
-		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) {
+		if (!expectingValue && (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) {
 			for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 				if (prefix === "-" && optionName$1.length !== 2) continue;
 				yield {
@@ -358,7 +358,7 @@ async function* suggestOptionAsync(optionNames$1, valueParser, hidden, context,
 			if (context.buffer.length > 0) {
 				const lastToken = context.buffer[context.buffer.length - 1];
 				if (optionNames$1.includes(lastToken)) shouldSuggestValues = true;
-			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (require_annotation_state.isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+"))) shouldSuggestValues = true;
 			if (shouldSuggestValues) for await (const suggestion of getSuggestionsWithDependencyAsync(valueParser, prefix, context.dependencyRegistry, context.exec)) yield suggestion;
 		}
 	}
@@ -888,7 +888,7 @@ function flag(...args) {
 		suggest(_context, prefix) {
 			if (require_usage.isSuggestionHidden(options.hidden)) return [];
 			const suggestions = [];
-			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/")) {
+			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
 				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
 					if (prefix === "-" && optionName$1.length !== 2) continue;
 					suggestions.push({
@@ -929,6 +929,221 @@ function flag(...args) {
 	});
 	return result;
 }
+function normalizeNegatableFlagNameList(names) {
+	return typeof names === "string" ? [names] : names;
+}
+function validateNoDuplicateOptionNames(names, label) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (seen.has(name)) throw new TypeError(`${label} has a duplicate name: "${name}".`);
+		seen.add(name);
+	}
+}
+function validateNoNegatableFlagNameCollision(positiveNames, negativeNames) {
+	const positiveSet = new Set(positiveNames);
+	for (const name of negativeNames) if (positiveSet.has(name)) throw new TypeError(`Negatable flag name is both positive and negative: "${name}".`);
+}
+function formatNegatableFlagDuplicateError(options, token) {
+	return options.errors?.duplicate ? typeof options.errors.duplicate === "function" ? options.errors.duplicate(token) : options.errors.duplicate : require_message.message`${require_message.optionName(token)} cannot be used multiple times.`;
+}
+function formatNegatableFlagConflictError(options, previousToken, token) {
+	return options.errors?.conflict ? typeof options.errors.conflict === "function" ? options.errors.conflict(previousToken, token) : options.errors.conflict : require_message.message`${require_message.optionName(previousToken)} and ${require_message.optionName(token)} cannot be used together.`;
+}
+function formatNegatableFlagUnexpectedValueError(options, optionName$1, value) {
+	return options.errors?.unexpectedValue ? typeof options.errors.unexpectedValue === "function" ? options.errors.unexpectedValue(optionName$1, value) : options.errors.unexpectedValue : require_message.message`Flag ${require_message.optionName(optionName$1)} does not accept a value, but got: ${value}.`;
+}
+function parseMatchedNegatableFlag(context, token, value, consumed, consumedOnFailure, buffer, options) {
+	if (context.state != null) return {
+		success: false,
+		consumed: consumedOnFailure,
+		error: context.state.value === value ? formatNegatableFlagDuplicateError(options, token) : formatNegatableFlagConflictError(options, context.state.token, token)
+	};
+	return {
+		success: true,
+		next: {
+			...context,
+			state: {
+				value,
+				token
+			},
+			buffer
+		},
+		consumed
+	};
+}
+/**
+* Creates a parser for a pair of command-line flags that explicitly enable or
+* disable a Boolean value.
+*
+* The positive names produce `true`; the negative names produce `false`.
+* Unlike {@link option}, this parser fails when neither side is present,
+* matching {@link flag} semantics. Wrap it in {@link optional} for a
+* tri-state override or {@link withDefault} for a concrete fallback.
+*
+* @param names The positive and negative option names to parse.
+* @param options Optional metadata and error customization.
+* @returns A {@link Parser} that produces `true` for positive names and
+*          `false` for negative names.
+* @throws {TypeError} If any option name is invalid, duplicated within one
+*         side, or shared by the positive and negative sides.
+* @since 1.1.0
+*/
+function negatableFlag(names, options = {}) {
+	const positiveNames = normalizeNegatableFlagNameList(names.positive);
+	const negativeNames = normalizeNegatableFlagNameList(names.negative);
+	require_validate.validateOptionNames(positiveNames, "Positive flag");
+	require_validate.validateOptionNames(negativeNames, "Negative flag");
+	validateNoDuplicateOptionNames(positiveNames, "Positive flag");
+	validateNoDuplicateOptionNames(negativeNames, "Negative flag");
+	validateNoNegatableFlagNameCollision(positiveNames, negativeNames);
+	const optionNames$1 = [...positiveNames, ...negativeNames];
+	const valueByName = /* @__PURE__ */ new Map();
+	for (const name of positiveNames) valueByName.set(name, true);
+	for (const name of negativeNames) valueByName.set(name, false);
+	const result = {
+		$valueType: [],
+		$stateType: [],
+		mode: "sync",
+		priority: 10,
+		usage: [{
+			type: "option",
+			names: optionNames$1,
+			...options.hidden != null && { hidden: options.hidden }
+		}],
+		leadingNames: new Set(optionNames$1),
+		acceptingAnyToken: false,
+		initialState: void 0,
+		parse(context) {
+			if (context.optionsTerminated) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.optionsTerminated ?? require_message.message`No more options can be parsed.`
+			};
+			else if (context.buffer.length < 1) return {
+				success: false,
+				consumed: 0,
+				error: options.errors?.endOfInput ?? require_message.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)
+			};
+			const directValue = valueByName.get(context.buffer[0]);
+			if (directValue != null) return parseMatchedNegatableFlag(context, context.buffer[0], directValue, context.buffer.slice(0, 1), 1, context.buffer.slice(1), options);
+			for (const name of optionNames$1) {
+				if (!name.startsWith("--") && !name.startsWith("/") && !name.startsWith("+") && !(name.startsWith("-") && name.length > 2)) continue;
+				const prefix = name.startsWith("/") ? `${name}:` : `${name}=`;
+				if (context.buffer[0].startsWith(prefix)) {
+					const value = context.buffer[0].slice(prefix.length);
+					return {
+						success: false,
+						consumed: 1,
+						error: formatNegatableFlagUnexpectedValueError(options, prefix.slice(0, -1), value)
+					};
+				}
+			}
+			for (const shortOption of optionNames$1) {
+				if (!shortOption.match(/^-[^-]$/)) continue;
+				if (!context.buffer[0].startsWith(shortOption)) continue;
+				return parseMatchedNegatableFlag(context, shortOption, valueByName.get(shortOption), [context.buffer[0].slice(0, 2)], 1, [`-${context.buffer[0].slice(2)}`, ...context.buffer.slice(1)], options);
+			}
+			const invalidOption = context.buffer[0];
+			if (options.errors?.noMatch) {
+				const candidates = /* @__PURE__ */ new Set();
+				for (const name of require_usage.extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = require_suggestion.findSimilar(invalidOption, candidates, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS);
+				return {
+					success: false,
+					consumed: 0,
+					error: typeof options.errors.noMatch === "function" ? options.errors.noMatch(invalidOption, suggestions) : options.errors.noMatch
+				};
+			}
+			const baseError = require_message.message`No matched option for ${require_message.optionName(invalidOption)}.`;
+			return {
+				success: false,
+				consumed: 0,
+				error: require_suggestion.createErrorWithSuggestions(baseError, invalidOption, context.usage, "option")
+			};
+		},
+		complete(state, _exec) {
+			if (state == null) return {
+				success: false,
+				error: options.errors?.missing ? typeof options.errors.missing === "function" ? options.errors.missing(positiveNames, negativeNames) : options.errors.missing : require_message.message`Required flag ${require_message.optionNames(optionNames$1)} is missing.`
+			};
+			return {
+				success: true,
+				value: state.value
+			};
+		},
+		suggest(_context, prefix) {
+			if (require_usage.isSuggestionHidden(options.hidden)) return [];
+			const suggestions = [];
+			if (prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/") || prefix.startsWith("+")) {
+				for (const optionName$1 of optionNames$1) if (optionName$1.startsWith(prefix)) {
+					if (prefix === "-" && optionName$1.length !== 2) continue;
+					suggestions.push({
+						kind: "literal",
+						text: optionName$1
+					});
+				}
+			}
+			return suggestions;
+		},
+		getDocFragments(_state, _defaultValue) {
+			if (require_usage.isDocHidden(options.hidden)) return {
+				fragments: [],
+				description: options.description
+			};
+			const fragments = [{
+				type: "entry",
+				term: {
+					type: "option",
+					names: optionNames$1
+				},
+				description: options.description
+			}];
+			return {
+				fragments,
+				description: options.description
+			};
+		},
+		[Symbol.for("Deno.customInspect")]() {
+			const args = [`positive: ${JSON.stringify(positiveNames)}`, `negative: ${JSON.stringify(negativeNames)}`];
+			return `negatableFlag({ ${args.join(", ")} })`;
+		}
+	};
+	Object.defineProperty(result, "validateValue", {
+		value(v) {
+			if (typeof v !== "boolean") {
+				const actualType = v === null ? "null" : typeof v;
+				return {
+					success: false,
+					error: require_message.message`${require_message.optionNames(optionNames$1)}: Expected a boolean value, but received ${actualType}.`
+				};
+			}
+			return {
+				success: true,
+				value: v
+			};
+		},
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+	Object.defineProperty(result, "placeholder", {
+		value: false,
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+	return result;
+}
 /**
 * Creates a parser that expects a single argument value.
 * This parser is typically used for positional arguments
@@ -1606,5 +1821,6 @@ exports.command = command;
 exports.constant = constant;
 exports.fail = fail;
 exports.flag = flag;
+exports.negatableFlag = negatableFlag;
 exports.option = option;
 exports.passThrough = passThrough;

package/dist/primitives.d.cts

@@ -237,6 +237,110 @@ interface FlagErrorOptions {
  * ```
  */
 declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+/**
+ * A non-empty list of option names, or a single option name.
+ * @since 1.1.0
+ */
+type NegatableFlagNameList = OptionName | readonly [OptionName, ...readonly OptionName[]];
+/**
+ * Option names for the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagNames {
+  /**
+   * Option names that produce `true`.
+   */
+  readonly positive: NegatableFlagNameList;
+  /**
+   * Option names that produce `false`.
+   */
+  readonly negative: NegatableFlagNameList;
+}
+/**
+ * Options for the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagOptions {
+  /**
+   * The description of the flag pair, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * Controls flag visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   */
+  readonly hidden?: HiddenVisibility;
+  /**
+   * Error message customization options.
+   */
+  readonly errors?: NegatableFlagErrorOptions;
+}
+/**
+ * Options for customizing error messages in the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagErrorOptions {
+  /**
+   * Custom error message when neither flag is provided.
+   * Can be a static message or a function that receives the positive and
+   * negative option names.
+   */
+  readonly missing?: Message | ((positiveNames: readonly string[], negativeNames: readonly string[]) => Message);
+  /**
+   * Custom error message when options are terminated (after --).
+   */
+  readonly optionsTerminated?: Message;
+  /**
+   * Custom error message when input is empty but a flag is expected.
+   */
+  readonly endOfInput?: Message;
+  /**
+   * Custom error message when the same polarity is used multiple times.
+   */
+  readonly duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when both positive and negative flags are used.
+   */
+  readonly conflict?: Message | ((previousToken: string, token: string) => Message);
+  /**
+   * Custom error message when a flag receives an unexpected value.
+   */
+  readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
+  /**
+   * Custom error message when no matching flag is found.
+   */
+  readonly noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
+}
+/**
+ * State stored by the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagState {
+  readonly value: boolean;
+  readonly token: string;
+}
+/**
+ * Creates a parser for a pair of command-line flags that explicitly enable or
+ * disable a Boolean value.
+ *
+ * The positive names produce `true`; the negative names produce `false`.
+ * Unlike {@link option}, this parser fails when neither side is present,
+ * matching {@link flag} semantics. Wrap it in {@link optional} for a
+ * tri-state override or {@link withDefault} for a concrete fallback.
+ *
+ * @param names The positive and negative option names to parse.
+ * @param options Optional metadata and error customization.
+ * @returns A {@link Parser} that produces `true` for positive names and
+ *          `false` for negative names.
+ * @throws {TypeError} If any option name is invalid, duplicated within one
+ *         side, or shared by the positive and negative sides.
+ * @since 1.1.0
+ */
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -483,4 +587,4 @@ interface PassThroughOptions {
  */
 declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/primitives.d.ts

@@ -237,6 +237,110 @@ interface FlagErrorOptions {
  * ```
  */
 declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+/**
+ * A non-empty list of option names, or a single option name.
+ * @since 1.1.0
+ */
+type NegatableFlagNameList = OptionName | readonly [OptionName, ...readonly OptionName[]];
+/**
+ * Option names for the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagNames {
+  /**
+   * Option names that produce `true`.
+   */
+  readonly positive: NegatableFlagNameList;
+  /**
+   * Option names that produce `false`.
+   */
+  readonly negative: NegatableFlagNameList;
+}
+/**
+ * Options for the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagOptions {
+  /**
+   * The description of the flag pair, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * Controls flag visibility:
+   *
+   * - `true`: hide from usage, docs, and suggestions
+   * - `"usage"`: hide from usage only
+   * - `"doc"`: hide from docs only
+   * - `"help"`: hide from usage and docs, keep suggestions
+   */
+  readonly hidden?: HiddenVisibility;
+  /**
+   * Error message customization options.
+   */
+  readonly errors?: NegatableFlagErrorOptions;
+}
+/**
+ * Options for customizing error messages in the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagErrorOptions {
+  /**
+   * Custom error message when neither flag is provided.
+   * Can be a static message or a function that receives the positive and
+   * negative option names.
+   */
+  readonly missing?: Message | ((positiveNames: readonly string[], negativeNames: readonly string[]) => Message);
+  /**
+   * Custom error message when options are terminated (after --).
+   */
+  readonly optionsTerminated?: Message;
+  /**
+   * Custom error message when input is empty but a flag is expected.
+   */
+  readonly endOfInput?: Message;
+  /**
+   * Custom error message when the same polarity is used multiple times.
+   */
+  readonly duplicate?: Message | ((token: string) => Message);
+  /**
+   * Custom error message when both positive and negative flags are used.
+   */
+  readonly conflict?: Message | ((previousToken: string, token: string) => Message);
+  /**
+   * Custom error message when a flag receives an unexpected value.
+   */
+  readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
+  /**
+   * Custom error message when no matching flag is found.
+   */
+  readonly noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
+}
+/**
+ * State stored by the {@link negatableFlag} parser.
+ * @since 1.1.0
+ */
+interface NegatableFlagState {
+  readonly value: boolean;
+  readonly token: string;
+}
+/**
+ * Creates a parser for a pair of command-line flags that explicitly enable or
+ * disable a Boolean value.
+ *
+ * The positive names produce `true`; the negative names produce `false`.
+ * Unlike {@link option}, this parser fails when neither side is present,
+ * matching {@link flag} semantics. Wrap it in {@link optional} for a
+ * tri-state override or {@link withDefault} for a concrete fallback.
+ *
+ * @param names The positive and negative option names to parse.
+ * @param options Optional metadata and error customization.
+ * @returns A {@link Parser} that produces `true` for positive names and
+ *          `false` for negative names.
+ * @throws {TypeError} If any option name is invalid, duplicated within one
+ *         side, or shared by the positive and negative sides.
+ * @since 1.1.0
+ */
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -483,4 +587,4 @@ interface PassThroughOptions {
  */
 declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
 //#endregion
-export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, option, passThrough };
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };