@optique/core 1.4.0-dev.2683 → 1.4.0-dev.2709

package/dist/internal/empty-input.cjs

@@ -0,0 +1,368 @@
+
+//#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
+exports.UNCHANGED = UNCHANGED;
+exports.acceptsEmptyInput = acceptsEmptyInput;
+exports.defineEmptyInputFacts = defineEmptyInputFacts;
+exports.failingStepFacts = failingStepFacts;
+exports.getEmptyInputFacts = getEmptyInputFacts;
+exports.longestMatchFacts = longestMatchFacts;
+exports.multipleFacts = multipleFacts;
+exports.objectFacts = objectFacts;
+exports.optionalLikeFacts = optionalLikeFacts;
+exports.orFacts = orFacts;
+exports.resolveEmptyStepState = resolveEmptyStepState;
+exports.tupleFacts = tupleFacts;
+exports.withEmptyInputFacts = withEmptyInputFacts;