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

package/dist/primitives.js

@@ -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 (isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (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 (isAnnotationWrappedInitialState(context.state) && context.buffer.length === 0 && (context.exec?.path?.length ?? 0) === 0 && !(prefix.startsWith("--") || prefix.startsWith("-") || prefix.startsWith("/"))) shouldSuggestValues = true;
+			} else if (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 (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 : 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 : message`${optionName(previousToken)} and ${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 : message`Flag ${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);
+	validateOptionNames(positiveNames, "Positive flag");
+	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 ?? 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)
+			};
+			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 extractOptionNames(context.usage)) candidates.add(name);
+				const suggestions = findSimilar(invalidOption, candidates, 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 = message`No matched option for ${optionName(invalidOption)}.`;
+			return {
+				success: false,
+				consumed: 0,
+				error: 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 : message`Required flag ${optionNames(optionNames$1)} is missing.`
+			};
+			return {
+				success: true,
+				value: state.value
+			};
+		},
+		suggest(_context, prefix) {
+			if (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 (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: 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
@@ -1601,4 +1816,4 @@ function passThrough(options = {}) {
 }
 
 //#endregion
-export { argument, command, constant, fail, flag, option, passThrough };
+export { argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/valueparser.cjs

@@ -2151,34 +2151,18 @@ function macAddress(options) {
 		if (sep === "none") return formatted.join("");
 		return formatted.join(sep);
 	}
-	function normalizeMac(value) {
-		if (typeof value !== "string") return metavar;
-		let octets;
-		let detectedSep;
-		if (value.includes(":")) {
-			octets = value.split(":");
-			detectedSep = ":";
-		} else if (value.includes("-")) {
-			octets = value.split("-");
-			detectedSep = "-";
-		} else if (value.includes(".")) {
-			const groups = value.split(".");
-			if (groups.length !== 3 || !groups.every((g) => /^[0-9a-fA-F]{4}$/.test(g))) return value;
-			octets = groups.flatMap((g) => [g.slice(0, 2), g.slice(2)]);
-			detectedSep = ".";
-		} else {
-			if (value.length !== 12) return value;
-			octets = [];
-			for (let i = 0; i < value.length; i += 2) octets.push(value.slice(i, i + 2));
-			detectedSep = "none";
+	let macParsing = false;
+	function normalizeMacValue(value, fallback) {
+		if (macParsing) return value;
+		macParsing = true;
+		try {
+			const result = parserObj.parse(value);
+			return result.success ? result.value : fallback;
+		} catch {
+			return fallback;
+		} finally {
+			macParsing = false;
 		}
-		if (octets.length !== 6 || !octets.every((o) => /^[0-9a-fA-F]{1,2}$/.test(o))) return value;
-		octets = octets.map((o) => o.padStart(2, "0"));
-		let sep;
-		if (outputSeparator != null) sep = outputSeparator;
-		else if (separator !== "any") sep = separator;
-		else sep = detectedSep;
-		return joinOctets(octets, sep);
 	}
 	const parserObj = {
 		mode: "sync",
@@ -2263,44 +2247,15 @@ function macAddress(options) {
 				value: joinOctets(octets, finalSeparator)
 			};
 		},
-		format: normalizeMac
-	};
-	const macParser = parserObj;
-	let macParsing = false;
-	Object.defineProperty(parserObj, "format", {
-		value(v) {
-			if (typeof v !== "string") return metavar;
-			if (macParsing) return v;
-			macParsing = true;
-			try {
-				const result = macParser.parse(v);
-				return result.success ? result.value : v;
-			} catch {
-				return v;
-			} finally {
-				macParsing = false;
-			}
-		},
-		configurable: true,
-		enumerable: true
-	});
-	Object.defineProperty(parserObj, "normalize", {
-		value(v) {
-			if (typeof v !== "string") return v;
-			if (macParsing) return v;
-			macParsing = true;
-			try {
-				const result = macParser.parse(v);
-				return result.success ? result.value : v;
-			} catch {
-				return v;
-			} finally {
-				macParsing = false;
-			}
+		format(value) {
+			if (typeof value !== "string") return metavar;
+			return normalizeMacValue(value, value);
 		},
-		configurable: true,
-		enumerable: true
-	});
+		normalize(value) {
+			if (typeof value !== "string") return value;
+			return normalizeMacValue(value, value);
+		}
+	};
 	return parserObj;
 }
 /**

package/dist/valueparser.js

@@ -2151,34 +2151,18 @@ function macAddress(options) {
 		if (sep === "none") return formatted.join("");
 		return formatted.join(sep);
 	}
-	function normalizeMac(value) {
-		if (typeof value !== "string") return metavar;
-		let octets;
-		let detectedSep;
-		if (value.includes(":")) {
-			octets = value.split(":");
-			detectedSep = ":";
-		} else if (value.includes("-")) {
-			octets = value.split("-");
-			detectedSep = "-";
-		} else if (value.includes(".")) {
-			const groups = value.split(".");
-			if (groups.length !== 3 || !groups.every((g) => /^[0-9a-fA-F]{4}$/.test(g))) return value;
-			octets = groups.flatMap((g) => [g.slice(0, 2), g.slice(2)]);
-			detectedSep = ".";
-		} else {
-			if (value.length !== 12) return value;
-			octets = [];
-			for (let i = 0; i < value.length; i += 2) octets.push(value.slice(i, i + 2));
-			detectedSep = "none";
+	let macParsing = false;
+	function normalizeMacValue(value, fallback) {
+		if (macParsing) return value;
+		macParsing = true;
+		try {
+			const result = parserObj.parse(value);
+			return result.success ? result.value : fallback;
+		} catch {
+			return fallback;
+		} finally {
+			macParsing = false;
 		}
-		if (octets.length !== 6 || !octets.every((o) => /^[0-9a-fA-F]{1,2}$/.test(o))) return value;
-		octets = octets.map((o) => o.padStart(2, "0"));
-		let sep;
-		if (outputSeparator != null) sep = outputSeparator;
-		else if (separator !== "any") sep = separator;
-		else sep = detectedSep;
-		return joinOctets(octets, sep);
 	}
 	const parserObj = {
 		mode: "sync",
@@ -2263,44 +2247,15 @@ function macAddress(options) {
 				value: joinOctets(octets, finalSeparator)
 			};
 		},
-		format: normalizeMac
-	};
-	const macParser = parserObj;
-	let macParsing = false;
-	Object.defineProperty(parserObj, "format", {
-		value(v) {
-			if (typeof v !== "string") return metavar;
-			if (macParsing) return v;
-			macParsing = true;
-			try {
-				const result = macParser.parse(v);
-				return result.success ? result.value : v;
-			} catch {
-				return v;
-			} finally {
-				macParsing = false;
-			}
-		},
-		configurable: true,
-		enumerable: true
-	});
-	Object.defineProperty(parserObj, "normalize", {
-		value(v) {
-			if (typeof v !== "string") return v;
-			if (macParsing) return v;
-			macParsing = true;
-			try {
-				const result = macParser.parse(v);
-				return result.success ? result.value : v;
-			} catch {
-				return v;
-			} finally {
-				macParsing = false;
-			}
+		format(value) {
+			if (typeof value !== "string") return metavar;
+			return normalizeMacValue(value, value);
 		},
-		configurable: true,
-		enumerable: true
-	});
+		normalize(value) {
+			if (typeof value !== "string") return value;
+			return normalizeMacValue(value, value);
+		}
+	};
 	return parserObj;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.1.0-dev.1998+3e697633",
+  "version": "1.1.0-dev.2053",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",