@optique/core 1.4.0-dev.2708 → 1.4.0-dev.2711

package/dist/internal/empty-input.js

@@ -0,0 +1,355 @@
+//#region src/internal/empty-input.ts
+/**
+* The state of an empty step that leaves its input state unchanged.
+* @internal
+*/
+const UNCHANGED = Object.freeze({ unchanged: true });
+/**
+* Returns the state that an empty step produces from the given initial
+* state.
+* @param next The step's resulting state.
+* @param initialState The state the step started from.
+* @returns The resulting state.
+* @internal
+*/
+function resolveEmptyStepState(next, initialState) {
+	return "unchanged" in next ? initialState : next.state(initialState);
+}
+const emptyInputFactsKey = Symbol("emptyInputFacts");
+const UNKNOWN = Object.freeze({});
+/**
+* Attaches empty-input facts to a parser.  The facts are stored as a
+* non-enumerable property, so object spread does not copy them, and they
+* are bound to the parser's current `parse`, `complete`, and
+* `initialState`, so replacing any of those invalidates them.
+* @param parser The parser to annotate.
+* @param facts The facts to attach.
+* @internal
+*/
+function defineEmptyInputFacts(parser, facts) {
+	if (Object.keys(facts).length < 1) return;
+	Object.defineProperty(parser, emptyInputFactsKey, {
+		value: {
+			facts,
+			parse: parser.parse,
+			complete: parser.complete,
+			...Object.getOwnPropertyDescriptor(parser, "initialState")?.get == null ? { initialState: { value: parser.initialState } } : {}
+		},
+		configurable: true,
+		enumerable: false,
+		writable: false
+	});
+}
+/**
+* Returns the empty-input facts of a parser, or an empty object when the
+* facts are unknown.
+* @param parser The parser to inspect.
+* @returns The facts known for the parser.
+* @internal
+*/
+function getEmptyInputFacts(parser) {
+	const stored = parser[emptyInputFactsKey];
+	if (stored == null || stored.parse !== parser.parse || stored.complete !== parser.complete || stored.initialState != null && stored.initialState.value !== parser.initialState) return UNKNOWN;
+	return stored.facts;
+}
+/**
+* Returns whether `parse(parser, [])` succeeds, when that is known from the
+* facts.
+* @param facts The parser's facts.
+* @returns `true` or `false` when known, `undefined` otherwise.
+* @internal
+*/
+function acceptsEmptyInput(facts) {
+	if (facts.step === "failure") return false;
+	if (facts.step == null) return void 0;
+	return facts.afterStep;
+}
+/**
+* Returns the facts of a parser that fails its empty step and whose
+* completion from the initial state has the given outcome.
+* @param fromInitial Whether completion from the initial state succeeds.
+* @returns The facts.
+* @internal
+*/
+function failingStepFacts(fromInitial) {
+	return {
+		step: "failure",
+		fromInitial
+	};
+}
+/**
+* Returns whether `complete()` succeeds after the parser was offered an
+* empty step whose state change was kept (on success) or discarded (on
+* failure).
+* @param facts The parser's facts.
+* @returns The outcome, or `undefined` when unknown.
+* @internal
+*/
+function completionAfterOptionalStep(facts) {
+	if (facts.step === "failure") return facts.fromInitial;
+	if (facts.step == null) return void 0;
+	return facts.afterStep;
+}
+/**
+* The state of a wrapper that stores its child's resulting state as the
+* only element of a fresh array.
+*/
+function wrapInFreshArray(child, childInitialState) {
+	return { state: () => [resolveEmptyStepState(child, childInitialState)] };
+}
+/**
+* Computes the facts of `optional(p)` and `withDefault(p, value)` when
+* completing the wrapper from its initial state is known to succeed.
+* @param child The facts of the wrapped parser.
+* @param childInitialState The wrapped parser's initial state.
+* @param fromInitial Whether completing the wrapper from its initial state
+*                    succeeds, or `undefined` when unknown.
+* @returns The facts of the wrapper.
+* @internal
+*/
+function optionalLikeFacts(child, childInitialState, fromInitial) {
+	if (child.step === "failure") return {
+		step: "success",
+		next: UNCHANGED,
+		afterStep: fromInitial,
+		fromInitial
+	};
+	if (child.step == null) return { fromInitial };
+	return {
+		step: child.step,
+		...child.next == null ? {} : { next: wrapInFreshArray(child.next, childInitialState) },
+		afterStep: child.afterStep,
+		fromInitial
+	};
+}
+/**
+* Computes the facts of `multiple(p, { min })` without a `max` bound.
+* @param child The facts of the repeated parser.
+* @param retainsItem Whether a successful empty step of the child is kept
+*                    as a repetition item, or `undefined` when unknown.
+* @param childInitialState The repeated parser's initial state.
+* @param min The minimum number of items.
+* @returns The facts of the repetition.
+* @internal
+*/
+function multipleFacts(child, retainsItem, childInitialState, min) {
+	const fromInitial = min < 1;
+	if (child.step === "failure") return min < 1 ? {
+		step: "success",
+		next: UNCHANGED,
+		afterStep: true,
+		fromInitial
+	} : {
+		step: "failure",
+		fromInitial
+	};
+	if (child.step == null || retainsItem == null) return { fromInitial };
+	if (!retainsItem) return {
+		step: "success",
+		next: UNCHANGED,
+		afterStep: min < 1,
+		fromInitial
+	};
+	return {
+		step: child.step,
+		...child.next == null ? {} : { next: wrapInFreshArray(child.next, childInitialState) },
+		afterStep: child.afterStep == null ? void 0 : min <= 1 && child.afterStep,
+		fromInitial
+	};
+}
+function selectZeroInputCandidate(branches) {
+	let index = -1;
+	let count = 0;
+	for (let i = 0; i < branches.length; i++) {
+		const branch = branches[i];
+		if (branch.matchesTokens) continue;
+		if (branch.facts.step == null) return void 0;
+		if (branch.facts.step !== "success") continue;
+		if (index < 0) index = i;
+		count++;
+	}
+	return count === 1 ? { index } : null;
+}
+/**
+* Computes the completion of `or()` and `longestMatch()` from their initial
+* state, which selects the unique zero-input candidate among the branches
+* that cannot match tokens.
+*/
+function exclusiveFromInitial(branches) {
+	const candidate = selectZeroInputCandidate(branches);
+	if (candidate === void 0) return void 0;
+	if (candidate === null) return false;
+	return branches[candidate.index].facts.afterStep;
+}
+/**
+* An exemplar of an exclusive combinator's state after it selected a branch.
+* It is a fresh, non-nullish value, which is all that repetition item checks
+* look at.
+*/
+function exclusiveNextState(index) {
+	return { state: () => [index, {
+		success: true,
+		consumed: []
+	}] };
+}
+/**
+* Computes the facts of `or()`.
+* @param branches The branches of the exclusive combinator.
+* @returns The facts of the combinator.
+* @internal
+*/
+function orFacts(branches) {
+	const candidate = selectZeroInputCandidate(branches);
+	if (candidate === void 0) return {};
+	const fromInitial = exclusiveFromInitial(branches);
+	if (candidate === null) return {
+		step: "failure",
+		fromInitial
+	};
+	return {
+		step: "success",
+		next: exclusiveNextState(candidate.index),
+		afterStep: branches[candidate.index].facts.afterStep,
+		fromInitial
+	};
+}
+/**
+* Computes the facts of `longestMatch()`, which selects the first branch
+* whose empty step succeeds, preferring a definitive success over a
+* provisional one.
+* @param branches The branches of the exclusive combinator.
+* @returns The facts of the combinator.
+* @internal
+*/
+function longestMatchFacts(branches) {
+	const fromInitial = exclusiveFromInitial(branches);
+	let best = null;
+	for (let i = 0; i < branches.length; i++) {
+		const facts = branches[i].facts;
+		if (facts.step == null) return { fromInitial };
+		if (facts.step === "failure") continue;
+		if (best == null || best.facts.step === "provisional" && facts.step === "success") best = {
+			index: i,
+			facts
+		};
+		if (best.facts.step === "success") break;
+	}
+	if (best == null) return {
+		step: "failure",
+		fromInitial
+	};
+	return {
+		step: best.facts.step,
+		next: exclusiveNextState(best.index),
+		afterStep: best.facts.afterStep,
+		fromInitial
+	};
+}
+function all(values) {
+	let unknown = false;
+	for (const value of values) {
+		if (value === false) return false;
+		if (value == null) unknown = true;
+	}
+	return unknown ? void 0 : true;
+}
+/**
+* Computes the facts of `tuple()`.  On an empty buffer `tuple()` offers
+* each child one zero-token step, stores the state of every child whose
+* step succeeded in a fresh state array, and skips the rest.
+* @param children The children in declaration order.
+* @returns The facts of the tuple.
+* @internal
+*/
+function tupleFacts(children) {
+	const fromInitial = all(children.map((c) => c.facts.fromInitial));
+	if (children.some((c) => c.facts.step == null)) return {
+		step: "success",
+		fromInitial
+	};
+	const afterStep = all(children.map((c) => completionAfterOptionalStep(c.facts)));
+	let next;
+	if (children.every((c) => c.facts.step === "failure")) next = UNCHANGED;
+	else if (children.every((c) => c.facts.step === "failure" || c.facts.next != null)) {
+		const steps = children.map((c) => c.facts.step === "failure" ? void 0 : c.facts.next);
+		next = { state: (initialState) => {
+			const slots = Array.isArray(initialState) ? initialState : [];
+			return steps.map((step, i) => step == null ? slots[i] : resolveEmptyStepState(step, slots[i]));
+		} };
+	}
+	return {
+		step: "success",
+		...next == null ? {} : { next },
+		afterStep,
+		fromInitial
+	};
+}
+/**
+* The state of `object()` after an empty step: a committed field state makes
+* it store a fresh record with the other fields unchanged.
+*/
+function objectNextState(changed) {
+	if (changed.length < 1) return UNCHANGED;
+	return { state: (initialState) => {
+		const record = initialState != null && typeof initialState === "object" ? { ...initialState } : {};
+		for (const [key, next] of changed) record[key] = resolveEmptyStepState(next, record[key]);
+		return record;
+	} };
+}
+/**
+* Computes the facts of a synchronous `object()`.  On an empty buffer
+* `object()` offers each field that cannot match tokens one zero-token
+* step, keeps the resulting state when it changed, and then succeeds only
+* if every field can complete.
+* @param children The fields.
+* @param keys The field keys, parallel to `children`.
+* @returns The facts of the object.
+* @internal
+*/
+function objectFacts(children, keys) {
+	const fromInitial = all(children.map((c) => c.facts.fromInitial));
+	const outcomes = [];
+	const changed = [];
+	let nextKnown = true;
+	for (const [i, child] of children.entries()) {
+		const { step, next } = child.facts;
+		if (child.matchesTokens || step === "failure") outcomes.push(child.facts.fromInitial);
+		else if (step == null) {
+			outcomes.push(void 0);
+			nextKnown = false;
+		} else if (next == null) {
+			nextKnown = false;
+			outcomes.push(child.facts.afterStep === child.facts.fromInitial ? child.facts.afterStep : void 0);
+		} else if ("unchanged" in next) outcomes.push(child.facts.fromInitial);
+		else {
+			changed.push([keys[i], next]);
+			outcomes.push(child.facts.afterStep);
+		}
+	}
+	const accepted = all(outcomes);
+	if (accepted == null) return { fromInitial };
+	if (!accepted) return {
+		step: "failure",
+		fromInitial
+	};
+	return {
+		step: "success",
+		...nextKnown ? { next: objectNextState(changed) } : {},
+		afterStep: true,
+		fromInitial
+	};
+}
+/**
+* Attaches empty-input facts to a parser and returns the parser.
+* @param parser The parser to annotate.
+* @param facts The facts to attach.
+* @returns The same parser.
+* @internal
+*/
+function withEmptyInputFacts(parser, facts) {
+	defineEmptyInputFacts(parser, facts);
+	return parser;
+}
+
+//#endregion
+export { UNCHANGED, acceptsEmptyInput, defineEmptyInputFacts, failingStepFacts, getEmptyInputFacts, longestMatchFacts, multipleFacts, objectFacts, optionalLikeFacts, orFacts, resolveEmptyStepState, tupleFacts, withEmptyInputFacts };

package/dist/internal/usage.cjs

@@ -0,0 +1,248 @@
+
+//#region src/internal/usage.ts
+const EMPTY = {
+	visible: false,
+	omissible: true,
+	hidesRequired: false
+};
+function isHiddenLeaf(term, isHidden) {
+	return (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isHidden(term.hidden);
+}
+function isDegenerateLeaf(term) {
+	return term.type === "option" && term.names.length === 0 || term.type === "command" && term.name === "" || term.type === "argument" && term.metavar.length === 0 || term.type === "literal" && term.value === "";
+}
+function projectTerms(terms, isHidden) {
+	let visible = false;
+	let omissible = true;
+	let hidesRequired = false;
+	for (const term of terms) {
+		const projection = projectTerm(term, isHidden);
+		hidesRequired ||= projection.hidesRequired;
+		if (!projection.visible) continue;
+		visible = true;
+		omissible &&= projection.omissible;
+	}
+	return {
+		visible,
+		omissible,
+		hidesRequired
+	};
+}
+/**
+* Projects an alternative of an exclusive term.  Display filtering drops an
+* alternative whose leading command is hidden as a whole, trailing terms
+* included.
+*/
+function projectBranch(branch, isHidden) {
+	const first = branch[0];
+	if (first?.type === "command" && isHidden(first.hidden)) return {
+		...EMPTY,
+		hidesRequired: true
+	};
+	return projectTerms(branch, isHidden);
+}
+function projectTerm(term, isHidden) {
+	if (isHiddenLeaf(term, isHidden)) return {
+		...EMPTY,
+		hidesRequired: term.type !== "passthrough"
+	};
+	if (isDegenerateLeaf(term)) return EMPTY;
+	switch (term.type) {
+		case "argument":
+		case "option":
+		case "command":
+		case "literal": return {
+			visible: true,
+			omissible: false,
+			hidesRequired: false
+		};
+		case "passthrough":
+		case "ellipsis": return {
+			visible: true,
+			omissible: true,
+			hidesRequired: false
+		};
+		case "optional": {
+			const inner = projectTerms(term.terms, isHidden);
+			return {
+				...inner,
+				omissible: true,
+				hidesRequired: false
+			};
+		}
+		case "sequence": return projectTerms(term.terms, isHidden);
+		case "multiple": {
+			const inner = projectTerms(term.terms, isHidden);
+			return {
+				...inner,
+				omissible: term.min < 1 || inner.omissible,
+				hidesRequired: term.min > 0 && inner.hidesRequired
+			};
+		}
+		case "exclusive": {
+			let visible = false;
+			let omissible = false;
+			let hidesRequired = false;
+			for (const branch of term.terms) {
+				const projection = projectBranch(branch, isHidden);
+				hidesRequired ||= projection.hidesRequired;
+				if (!projection.visible) continue;
+				visible = true;
+				omissible ||= projection.omissible;
+			}
+			return {
+				visible,
+				omissible,
+				hidesRequired
+			};
+		}
+	}
+}
+/**
+* Returns the terms `X` when the visible part of `terms` is exactly
+* `optional(X)`, possibly nested, with a required `X`, and no required term
+* was hidden.
+*/
+function unwrapSingleOptional(terms, isHidden) {
+	if (projectTerms(terms, isHidden).hidesRequired) return void 0;
+	const visible = terms.filter((t) => projectTerm(t, isHidden).visible);
+	if (visible.length !== 1) return void 0;
+	const [only] = visible;
+	if (only.type !== "optional") return void 0;
+	const inner = projectTerms(only.terms, isHidden);
+	if (!inner.visible || inner.hidesRequired) return void 0;
+	if (inner.omissible) return unwrapSingleOptional(only.terms, isHidden);
+	return only.terms;
+}
+function resolveTerms(terms, isHidden) {
+	return terms.map((term) => resolveTerm(term, isHidden));
+}
+function resolveTerm(term, isHidden) {
+	switch (term.type) {
+		case "optional": return {
+			type: "optional",
+			terms: resolveTerms(term.terms, isHidden)
+		};
+		case "sequence": return {
+			type: "sequence",
+			terms: resolveTerms(term.terms, isHidden)
+		};
+		case "multiple": {
+			const terms = resolveTerms(term.terms, isHidden);
+			const resolved = {
+				type: "multiple",
+				terms,
+				min: term.min
+			};
+			if (term.acceptsEmpty == null) return resolved;
+			const projection = projectTerm(resolved, isHidden);
+			if (!projection.visible || projection.omissible === term.acceptsEmpty) return resolved;
+			if (term.acceptsEmpty) return {
+				type: "optional",
+				terms: [resolved]
+			};
+			if (term.min < 1) return resolved;
+			const required = unwrapSingleOptional(terms, isHidden);
+			return required == null ? resolved : {
+				...resolved,
+				terms: required
+			};
+		}
+		case "exclusive": {
+			const branches = term.terms.map((branch) => resolveTerms(branch, isHidden));
+			const resolved = {
+				type: "exclusive",
+				terms: branches
+			};
+			if (term.acceptsEmpty == null) return resolved;
+			const projection = projectTerm(resolved, isHidden);
+			if (!projection.visible || projection.omissible === term.acceptsEmpty) return resolved;
+			if (term.acceptsEmpty) {
+				const visible = branches.filter((branch) => projectBranch(branch, isHidden).visible);
+				return {
+					type: "optional",
+					terms: visible.length === 1 ? visible[0] : [{
+						type: "exclusive",
+						terms: visible
+					}]
+				};
+			}
+			const required = [];
+			for (const branch of branches) {
+				const branchProjection = projectBranch(branch, isHidden);
+				if (!branchProjection.visible || !branchProjection.omissible) {
+					required.push(branch);
+					continue;
+				}
+				const unwrapped = unwrapSingleOptional(branch, isHidden);
+				if (unwrapped == null) return resolved;
+				required.push(unwrapped);
+			}
+			return {
+				type: "exclusive",
+				terms: required
+			};
+		}
+		default: return term;
+	}
+}
+/**
+* Rewrites a usage so that plain synopsis notation reflects the recorded
+* empty-input behavior of its groups.
+*
+* Each `exclusive` or `multiple` term that records `acceptsEmpty` is drawn
+* as omissible exactly when its parser accepts an empty argument list,
+* using only exact local rewrites: a group that should be omissible is
+* wrapped in an optional term, and a group that should be required has
+* `optional(X)` alternatives or repeated items replaced by `X`.  A group
+* whose visible terms cannot be drawn that way keeps its declared notation.
+* Enclosing groups are resolved after their children, so their constraints
+* take precedence.
+*
+* The result records no `acceptsEmpty` fields, so resolving it again
+* returns an equal usage.  Hidden terms are kept; callers filter them for
+* display afterwards.
+* @param usage The usage to resolve.
+* @param isHidden Reports whether a term is hidden in the rendering context.
+* @returns The resolved usage.
+* @internal
+*/
+function resolveUsageForDisplay(usage, isHidden) {
+	return resolveTerms(usage, isHidden);
+}
+/**
+* Removes every `acceptsEmpty` record from a usage without changing how it
+* is drawn otherwise.
+* @param usage The usage to copy.
+* @returns The usage without records.
+* @internal
+*/
+function forgetEmptyInput(usage) {
+	return usage.map(forgetEmptyInputTerm);
+}
+function forgetEmptyInputTerm(term) {
+	switch (term.type) {
+		case "optional": return {
+			type: "optional",
+			terms: forgetEmptyInput(term.terms)
+		};
+		case "sequence": return {
+			type: "sequence",
+			terms: forgetEmptyInput(term.terms)
+		};
+		case "multiple": return {
+			type: "multiple",
+			terms: forgetEmptyInput(term.terms),
+			min: term.min
+		};
+		case "exclusive": return {
+			type: "exclusive",
+			terms: term.terms.map(forgetEmptyInput)
+		};
+		default: return term;
+	}
+}
+
+//#endregion
+exports.forgetEmptyInput = forgetEmptyInput;
+exports.resolveUsageForDisplay = resolveUsageForDisplay;

package/dist/internal/usage.d.cts

@@ -0,0 +1,42 @@
+import { HiddenVisibility, Usage } from "../usage.cjs";
+
+//#region src/internal/usage.d.ts
+
+/**
+ * Reports whether a term with the given visibility is hidden in the
+ * rendering context.
+ * @internal
+ */
+type HiddenPredicate = (hidden?: HiddenVisibility) => boolean;
+/**
+ * Rewrites a usage so that plain synopsis notation reflects the recorded
+ * empty-input behavior of its groups.
+ *
+ * Each `exclusive` or `multiple` term that records `acceptsEmpty` is drawn
+ * as omissible exactly when its parser accepts an empty argument list,
+ * using only exact local rewrites: a group that should be omissible is
+ * wrapped in an optional term, and a group that should be required has
+ * `optional(X)` alternatives or repeated items replaced by `X`.  A group
+ * whose visible terms cannot be drawn that way keeps its declared notation.
+ * Enclosing groups are resolved after their children, so their constraints
+ * take precedence.
+ *
+ * The result records no `acceptsEmpty` fields, so resolving it again
+ * returns an equal usage.  Hidden terms are kept; callers filter them for
+ * display afterwards.
+ * @param usage The usage to resolve.
+ * @param isHidden Reports whether a term is hidden in the rendering context.
+ * @returns The resolved usage.
+ * @internal
+ */
+declare function resolveUsageForDisplay(usage: Usage, isHidden: HiddenPredicate): Usage;
+/**
+ * Removes every `acceptsEmpty` record from a usage without changing how it
+ * is drawn otherwise.
+ * @param usage The usage to copy.
+ * @returns The usage without records.
+ * @internal
+ */
+declare function forgetEmptyInput(usage: Usage): Usage;
+//#endregion
+export { HiddenPredicate, forgetEmptyInput, resolveUsageForDisplay };

package/dist/internal/usage.d.ts

@@ -0,0 +1,42 @@
+import { HiddenVisibility, Usage } from "../usage.js";
+
+//#region src/internal/usage.d.ts
+
+/**
+ * Reports whether a term with the given visibility is hidden in the
+ * rendering context.
+ * @internal
+ */
+type HiddenPredicate = (hidden?: HiddenVisibility) => boolean;
+/**
+ * Rewrites a usage so that plain synopsis notation reflects the recorded
+ * empty-input behavior of its groups.
+ *
+ * Each `exclusive` or `multiple` term that records `acceptsEmpty` is drawn
+ * as omissible exactly when its parser accepts an empty argument list,
+ * using only exact local rewrites: a group that should be omissible is
+ * wrapped in an optional term, and a group that should be required has
+ * `optional(X)` alternatives or repeated items replaced by `X`.  A group
+ * whose visible terms cannot be drawn that way keeps its declared notation.
+ * Enclosing groups are resolved after their children, so their constraints
+ * take precedence.
+ *
+ * The result records no `acceptsEmpty` fields, so resolving it again
+ * returns an equal usage.  Hidden terms are kept; callers filter them for
+ * display afterwards.
+ * @param usage The usage to resolve.
+ * @param isHidden Reports whether a term is hidden in the rendering context.
+ * @returns The resolved usage.
+ * @internal
+ */
+declare function resolveUsageForDisplay(usage: Usage, isHidden: HiddenPredicate): Usage;
+/**
+ * Removes every `acceptsEmpty` record from a usage without changing how it
+ * is drawn otherwise.
+ * @param usage The usage to copy.
+ * @returns The usage without records.
+ * @internal
+ */
+declare function forgetEmptyInput(usage: Usage): Usage;
+//#endregion
+export { HiddenPredicate, forgetEmptyInput, resolveUsageForDisplay };