@thomasfosterau/effect-parse 0.1.0 → 0.2.0

package/dist/Input.js

@@ -1,312 +1,330 @@
-/**
- * Input types and the mutable parse {@link State} cursor.
- *
- * Like winnow, effect-parse parsers advance a mutable cursor rather than
- * returning the remaining input. A {@link State} wraps the original input
- * together with the current offset, the streaming (partial) flag, the
- * services available to the parser, and the details of the most recent
- * failure.
- *
- * Most users never touch `State` directly. It is exposed for writing custom
- * low-level parsers with `Parser.make`.
- *
- * @since 0.1.0
- */
+import * as Predicate from "effect/Predicate";
 import * as Context from "effect/Context";
+//#region src/Input.ts
+/**
+* Input types and the mutable parse {@link State} cursor.
+*
+* Like winnow, effect-parse parsers advance a mutable cursor rather than
+* returning the remaining input. A {@link State} wraps the original input
+* together with the current offset, the streaming (partial) flag, the
+* services available to the parser, and the details of the most recent
+* failure.
+*
+* Most users never touch `State` directly. It is exposed for writing custom
+* low-level parsers with `Parser.make`, and for drivers that run a parser's
+* `step` many times over one input, reusing a state with {@link State.reset}.
+*
+* @since 0.1.0
+*/
 /**
- * Converts a {@link Source} to the input parsers read: binary data becomes a
- * `Uint8Array` view of the same memory, everything else is returned as is.
- *
- * @example
- * ```ts
- * import { Input } from "@thomasfosterau/effect-parse"
- *
- * Input.fromSource(new Uint16Array([0x41]).buffer) // Uint8Array [0x41, 0x00]
- * ```
- *
- * @since 0.1.0
- * @category constructors
- */
-export const fromSource = (source) => {
-    if (typeof source === "string" || source instanceof Uint8Array || Array.isArray(source))
-        return source;
-    if (ArrayBuffer.isView(source))
-        return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
-    // An explicit length fixes the view's size even for a resizable buffer
-    if (isArrayBufferLike(source))
-        return new Uint8Array(source, 0, source.byteLength);
-    return source;
+* Converts a {@link Source} to the input parsers read: binary data becomes a
+* `Uint8Array` view of the same memory, everything else is returned as is.
+*
+* @example
+* ```ts
+* import { Input } from "@thomasfosterau/effect-parse"
+*
+* Input.fromSource(new Uint16Array([0x41]).buffer) // Uint8Array [0x41, 0x00]
+* ```
+*
+* @since 0.1.0
+* @category constructors
+*/
+const fromSource = (source) => {
+	if (Predicate.isString(source) || source instanceof Uint8Array || Array.isArray(source)) return source;
+	if (ArrayBuffer.isView(source)) return new Uint8Array(source.buffer, source.byteOffset, source.byteLength);
+	if (isArrayBufferLike(source)) return new Uint8Array(source, 0, source.byteLength);
+	return source;
 };
-const isArrayBufferLike = (u) => u instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && u instanceof SharedArrayBuffer);
+const isArrayBufferLike = (u) => u instanceof ArrayBuffer || globalThis.SharedArrayBuffer !== void 0 && u instanceof SharedArrayBuffer;
 /**
- * Sentinel returned by a parser step to signal failure. The failure details
- * are stored on the {@link State}.
- *
- * @since 0.1.0
- * @category failure
- */
-export const Fail = Symbol.for("effect-parse/Fail");
+* Sentinel returned by a parser step to signal failure. The failure details
+* are stored on the {@link State}.
+*
+* @since 0.1.0
+* @category failure
+*/
+const Fail = /*#__PURE__*/ Symbol.for("effect-parse/Fail");
 /**
- * The details of a parse failure.
- *
- * @since 0.1.0
- * @category failure
- */
-export class Failure {
-    offset;
-    kind;
-    expected;
-    context;
-    hasCause;
-    cause;
-    message;
-    needed;
-    constructor(
-    /** Offset into the input where the failure occurred. */
-    offset, 
-    /** The kind of parser that failed. */
-    kind, 
-    /** Rendered descriptions of what was expected at `offset`. */
-    expected, 
-    /** Context labels added by `Parser.context`, innermost first. */
-    context, 
-    /** Whether a user supplied cause is present. */
-    hasCause, 
-    /** A user supplied (typed) cause. */
-    cause, 
-    /** An optional free-form message. */
-    message, 
-    /** For `Incomplete` failures, how many more tokens are needed (0 if unknown). */
-    needed) {
-        this.offset = offset;
-        this.kind = kind;
-        this.expected = expected;
-        this.context = context;
-        this.hasCause = hasCause;
-        this.cause = cause;
-        this.message = message;
-        this.needed = needed;
-    }
-}
+* The details of a parse failure.
+*
+* @since 0.1.0
+* @category failure
+*/
+var Failure = class {
+	offset;
+	kind;
+	expected;
+	context;
+	hasCause;
+	cause;
+	message;
+	needed;
+	constructor(offset, kind, expected, context, hasCause, cause, message, needed) {
+		this.offset = offset;
+		this.kind = kind;
+		this.expected = expected;
+		this.context = context;
+		this.hasCause = hasCause;
+		this.cause = cause;
+		this.message = message;
+		this.needed = needed;
+	}
+};
 const empty = [];
+/** The failure a {@link State} starts with, before any step has failed. */
+const initialFailure = /*#__PURE__*/ new Failure(0, "Fail", empty, empty, false, void 0, void 0, 0);
 /** @internal */
-export const emptyStrings = empty;
+const emptyStrings = empty;
 /**
- * The mutable parsing cursor.
- *
- * @since 0.1.0
- * @category models
- */
-export class State {
-    /** The full input being parsed. */
-    input;
-    /** The current offset. Advanced by parsers, rewound on backtracking. */
-    pos;
-    /** The end offset (the input's length; in bits inside `Bits.bits`). */
-    end;
-    /** 0 = string, 1 = Uint8Array, 2 = array. */
-    inputKind;
-    /** Whether the input is partial (streaming): running out yields `Incomplete`. */
-    partial;
-    /** Services available to `Parser.service`. */
-    context;
-    /** Mode of the latest failure. Only meaningful after a step returned {@link Fail}. */
-    mode = "Backtrack";
-    /** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
-    failure;
-    /**
-     * The offset of a recoverable failure that occurred without consuming
-     * input (for example the last attempt of a `repeat`). Its
-     * expectations are merged into new failures at the same offset, producing
-     * messages like `expected digit or ")"`.
-     */
-    hintOffset = -1;
-    /** The expectations of the hint at {@link hintOffset}. */
-    hintExpected = empty;
-    /**
-     * The furthest recoverable failure seen so far, including failures that
-     * were later swallowed by backtracking (for example a trailing separator
-     * followed by an invalid element). It is reported instead of the final
-     * failure when it lies further into the input. This is the classic PEG
-     * "farthest failure" heuristic.
-     */
-    deepest = undefined;
-    /** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
-    recovered = undefined;
-    /** When defined, `Parser.trace` reports events here. */
-    tracer = undefined;
-    /** Current tracing depth. */
-    depth = 0;
-    /**
-     * The text encoding of a byte input, recorded by `Text` parsers when they
-     * fail so that errors can show the input as text.
-     */
-    encoding = undefined;
-    /**
-     * The checkpoints of a resumable streaming parse (see
-     * `ParserStream.parseAll`); `undefined` otherwise.
-     *
-     * @internal
-     */
-    resume = undefined;
-    constructor(source, options) {
-        const input = fromSource(source);
-        this.input = input;
-        this.end = input.length;
-        this.pos = options?.offset ?? 0;
-        this.partial = options?.partial ?? false;
-        this.context = options?.context ?? Context.empty();
-        this.inputKind = typeof input === "string" ? 0 : input instanceof Uint8Array ? 1 : 2;
-        this.failure = new Failure(0, "Fail", empty, empty, false, undefined, undefined, 0);
-    }
-    /**
-     * The number of input units (code units, bytes or elements) remaining.
-     */
-    remaining() {
-        return this.end - this.pos;
-    }
-    /**
-     * Whether the cursor is at the end of the input.
-     */
-    atEnd() {
-        return this.pos >= this.end;
-    }
-    /**
-     * Extracts the slice `[start, end)` of the input.
-     */
-    slice(start, end) {
-        const input = this.input;
-        switch (this.inputKind) {
-            case 0:
-                return input.slice(start, end);
-            case 1:
-                return input.subarray(start, end);
-            default:
-                return input.slice(start, end);
-        }
-    }
-    /**
-     * Records a recoverable failure at the current offset and returns {@link Fail}.
-     */
-    backtrack(kind, expected = empty, offset = this.pos) {
-        return this.failWith("Backtrack", this.makeFailure(offset, kind, expected));
-    }
-    /**
-     * Records an unrecoverable failure at the current offset and returns {@link Fail}.
-     */
-    cut(kind, expected = empty, offset = this.pos) {
-        return this.failWith("Cut", this.makeFailure(offset, kind, expected));
-    }
-    /**
-     * Records an `Incomplete` failure (only meaningful for partial input) and
-     * returns {@link Fail}.
-     */
-    incomplete(needed, expected = empty) {
-        return this.failWith("Incomplete", new Failure(this.pos, "Incomplete", expected, empty, false, undefined, undefined, needed));
-    }
-    /**
-     * Fails because the input ended: `Incomplete` for partial input, otherwise
-     * a `Backtrack` failure of the given kind.
-     */
-    eoi(kind, expected, needed) {
-        return this.partial ? this.incomplete(needed, expected) : this.backtrack(kind, expected);
-    }
-    /**
-     * Records a failure carrying a user supplied cause.
-     */
-    failCause(mode, kind, cause, offset = this.pos) {
-        return this.failWith(mode, new Failure(offset, kind, empty, empty, true, cause, undefined, 0));
-    }
-    /**
-     * Records a failure carrying a message.
-     */
-    failMessage(mode, kind, message, offset = this.pos) {
-        return this.failWith(mode, new Failure(offset, kind, empty, empty, false, undefined, message, 0));
-    }
-    /**
-     * Records the given failure and returns {@link Fail}.
-     */
-    failWith(mode, failure) {
-        this.mode = mode;
-        this.failure = failure;
-        if (mode === "Backtrack" && (this.deepest === undefined || failure.offset >= this.deepest.offset)) {
-            this.deepest = failure;
-        }
-        return Fail;
-    }
-    /**
-     * Replaces the details of the current failure (for example to add context),
-     * keeping the record of the furthest failure consistent.
-     */
-    replaceFailure(failure) {
-        if (this.deepest === this.failure)
-            this.deepest = failure;
-        this.failure = failure;
-    }
-    /**
-     * The failure to report to the user: the current failure, or the furthest
-     * failure if it lies beyond the current one and the current failure is a
-     * plain syntax error (no user cause or message).
-     */
-    reportedFailure() {
-        const f = this.failure;
-        const d = this.deepest;
-        if (d === undefined || d === f || d.offset <= f.offset || this.mode === "Incomplete" ||
-            f.hasCause || f.message !== undefined) {
-            return f;
-        }
-        const context = d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))];
-        return new Failure(d.offset, d.kind, d.expected, context, d.hasCause, d.cause, d.message, d.needed);
-    }
-    /**
-     * Records that, at `offset`, any of `expected` could also have been
-     * accepted. Used by parsers that stop without failing, such as `opt`,
-     * `repeat` and `Ascii.digit1`.
-     */
-    setHint(offset, expected) {
-        if (this.hintOffset === offset) {
-            this.hintExpected = mergeExpected(this.hintExpected, expected);
-        }
-        else {
-            this.hintOffset = offset;
-            this.hintExpected = expected;
-        }
-    }
-    /** @internal */
-    makeFailure(offset, kind, expected) {
-        if (this.hintOffset === offset && this.hintExpected.length > 0) {
-            expected = mergeExpected(this.hintExpected, expected);
-        }
-        return new Failure(offset, kind, expected, empty, false, undefined, undefined, 0);
-    }
-}
+* The mutable parsing cursor.
+*
+* @since 0.1.0
+* @category models
+*/
+var State = class {
+	/** The full input being parsed. */
+	input;
+	/** The end offset (the input's length; in bits inside `Bits.bits`). */
+	end;
+	/** 0 = string, 1 = Uint8Array, 2 = array. */
+	inputKind;
+	/** Whether the input is partial (streaming): running out yields `Incomplete`. */
+	partial;
+	/** Services available to `Parser.service`. */
+	context;
+	/** Mode of the latest failure. Only meaningful after a step returned {@link Fail}. */
+	mode = "Backtrack";
+	/** Details of the latest failure. Only meaningful after a step returned {@link Fail}. */
+	failure;
+	/**
+	* The offset of a recoverable failure that occurred without consuming
+	* input (for example the last attempt of a `repeat`). Its
+	* expectations are merged into new failures at the same offset, producing
+	* messages like `expected digit or ")"`.
+	*/
+	hintOffset = -1;
+	/** The expectations of the hint at {@link hintOffset}. */
+	hintExpected = empty;
+	/**
+	* The furthest recoverable failure seen so far, including failures that
+	* were later swallowed by backtracking (for example a trailing separator
+	* followed by an invalid element). It is reported instead of the final
+	* failure when it lies further into the input. This is the classic PEG
+	* "farthest failure" heuristic. `Parser.cut` keeps only the failures
+	* recorded inside it when it commits, and `Parser.peek` and `Parser.not`
+	* forget the failures of a lookahead that succeeded.
+	*/
+	deepest = void 0;
+	/** When defined, `Parser.resumeAfter`/`retryAfter` record failures here. */
+	recovered = void 0;
+	/** When defined, `Parser.trace` reports events here. */
+	tracer = void 0;
+	/** Current tracing depth. */
+	depth = 0;
+	/**
+	* The text encoding of a byte input, recorded by `Text` parsers when they
+	* fail so that errors can show the input as text.
+	*/
+	encoding = void 0;
+	/**
+	* The checkpoints of a resumable streaming parse (see
+	* `ParserStream.parseAll`); `undefined` otherwise.
+	*
+	* @internal
+	*/
+	resume = void 0;
+	/**
+	* The tree builder of a `Syntax` parse; `undefined` otherwise.
+	*
+	* @internal
+	*/
+	syntax = void 0;
+	constructor(source, options) {
+		const input = fromSource(source);
+		this.input = input;
+		this.end = input.length;
+		this.pos = options?.offset ?? 0;
+		this.partial = options?.partial ?? false;
+		this.context = options?.context ?? Context.empty();
+		this.inputKind = Predicate.isString(input) ? 0 : input instanceof Uint8Array ? 1 : 2;
+		this.failure = initialFailure;
+	}
+	/**
+	* Prepares the state for another run over the same input, starting at
+	* `offset`: afterwards it behaves exactly like
+	* `new State(state.input, { ...options, offset })`, without allocating a
+	* new state.
+	*
+	* Every per-run field is reset: the cursor and end, the latest failure,
+	* hints and furthest failure, recorded recoveries, the tracer and tracing
+	* depth, the recorded encoding and streaming checkpoints. Like the
+	* constructor, `partial` defaults to `false` and `context` to the empty
+	* context, so pass them again on every reset.
+	*
+	* Use it to run many small parses over one buffer, for example one per
+	* token, with `parser.step`. A state can be reused after any run,
+	* including one that failed, returned `Incomplete` or threw.
+	*
+	* @example
+	* ```ts
+	* import { Ascii, Input } from "@thomasfosterau/effect-parse"
+	*
+	* const state = new Input.State("12 34")
+	* Ascii.decUint.step(state) // 12
+	* state.reset(3)
+	* Ascii.decUint.step(state) // 34
+	* ```
+	*
+	* @since 0.2.0
+	*/
+	reset(offset = 0, options) {
+		this.pos = offset;
+		this.end = this.input.length;
+		this.partial = options?.partial ?? false;
+		this.context = options?.context ?? Context.empty();
+		this.mode = "Backtrack";
+		this.failure = initialFailure;
+		this.hintOffset = -1;
+		this.hintExpected = empty;
+		this.deepest = void 0;
+		this.recovered = void 0;
+		this.tracer = void 0;
+		this.depth = 0;
+		this.encoding = void 0;
+		this.resume = void 0;
+		return this;
+	}
+	/**
+	* The number of input units (code units, bytes or elements) remaining.
+	*/
+	remaining() {
+		return this.end - this.pos;
+	}
+	/**
+	* Whether the cursor is at the end of the input.
+	*/
+	atEnd() {
+		return this.pos >= this.end;
+	}
+	/**
+	* Extracts the slice `[start, end)` of the input.
+	*/
+	slice(start, end) {
+		const input = this.input;
+		switch (this.inputKind) {
+			case 0: return input.slice(start, end);
+			case 1: return input.subarray(start, end);
+			default: return input.slice(start, end);
+		}
+	}
+	/**
+	* Records a recoverable failure at the current offset and returns {@link Fail}.
+	*/
+	backtrack(kind, expected = empty, offset = this.pos) {
+		return this.failWith("Backtrack", this.makeFailure(offset, kind, expected));
+	}
+	/**
+	* Records an unrecoverable failure at the current offset and returns {@link Fail}.
+	*/
+	cut(kind, expected = empty, offset = this.pos) {
+		return this.failWith("Cut", this.makeFailure(offset, kind, expected));
+	}
+	/**
+	* Records an `Incomplete` failure (only meaningful for partial input) and
+	* returns {@link Fail}.
+	*/
+	incomplete(needed, expected = empty) {
+		return this.failWith("Incomplete", new Failure(this.pos, "Incomplete", expected, empty, false, void 0, void 0, needed));
+	}
+	/**
+	* Fails because the input ended: `Incomplete` for partial input, otherwise
+	* a `Backtrack` failure of the given kind.
+	*/
+	eoi(kind, expected, needed) {
+		return this.partial ? this.incomplete(needed, expected) : this.backtrack(kind, expected);
+	}
+	/**
+	* Records a failure carrying a user supplied cause.
+	*/
+	failCause(mode, kind, cause, offset = this.pos) {
+		return this.failWith(mode, new Failure(offset, kind, empty, empty, true, cause, void 0, 0));
+	}
+	/**
+	* Records a failure carrying a message.
+	*/
+	failMessage(mode, kind, message, offset = this.pos) {
+		return this.failWith(mode, new Failure(offset, kind, empty, empty, false, void 0, message, 0));
+	}
+	/**
+	* Records the given failure and returns {@link Fail}.
+	*/
+	failWith(mode, failure) {
+		this.mode = mode;
+		this.failure = failure;
+		if (mode === "Backtrack" && (this.deepest === void 0 || failure.offset >= this.deepest.offset)) this.deepest = failure;
+		return Fail;
+	}
+	/**
+	* Replaces the details of the current failure (for example to add context),
+	* keeping the record of the furthest failure consistent.
+	*/
+	replaceFailure(failure) {
+		if (this.deepest === this.failure) this.deepest = failure;
+		this.failure = failure;
+	}
+	/**
+	* The failure to report to the user: the current failure, or the furthest
+	* failure if it lies beyond the current one and the current failure is a
+	* plain syntax error (no user cause or message).
+	*/
+	reportedFailure() {
+		const f = this.failure;
+		const d = this.deepest;
+		if (d === void 0 || d === f || d.offset <= f.offset || this.mode === "Incomplete" || f.hasCause || f.message !== void 0) return f;
+		const context = d.context.length === 0 ? f.context : [...d.context, ...f.context.filter((l) => !d.context.includes(l))];
+		return new Failure(d.offset, d.kind, d.expected, context, d.hasCause, d.cause, d.message, d.needed);
+	}
+	/**
+	* Records that, at `offset`, any of `expected` could also have been
+	* accepted. Used by parsers that stop without failing, such as `opt`,
+	* `repeat` and `Ascii.digit1`.
+	*/
+	setHint(offset, expected) {
+		if (this.hintOffset === offset) this.hintExpected = mergeExpected(this.hintExpected, expected);
+		else {
+			this.hintOffset = offset;
+			this.hintExpected = expected;
+		}
+	}
+	/** @internal */
+	makeFailure(offset, kind, expected) {
+		if (this.hintOffset === offset && this.hintExpected.length > 0) expected = mergeExpected(this.hintExpected, expected);
+		return new Failure(offset, kind, expected, empty, false, void 0, void 0, 0);
+	}
+};
 /** @internal */
-export const mergeExpected = (a, b) => {
-    if (a.length === 0)
-        return b;
-    if (b.length === 0)
-        return a;
-    const out = a.slice();
-    for (const e of b) {
-        if (!out.includes(e))
-            out.push(e);
-    }
-    return out;
+const mergeExpected = (a, b) => {
+	if (a.length === 0) return b;
+	if (b.length === 0) return a;
+	const out = a.slice();
+	for (const e of b) if (!out.includes(e)) out.push(e);
+	return out;
 };
 /**
- * Combines the failures of two alternatives: the furthest failure wins, and
- * failures at the same offset have their expectations merged.
- *
- * @internal
- */
-export const mergeFailures = (a, b) => {
-    if (a.offset > b.offset)
-        return a;
-    if (b.offset > a.offset)
-        return b;
-    const expected = mergeExpected(a.expected, b.expected);
-    if (expected === b.expected)
-        return b;
-    return new Failure(b.offset, b.kind, expected, b.context.length > 0 ? b.context : a.context, b.hasCause || a.hasCause, b.hasCause ? b.cause : a.cause, b.message ?? a.message, b.needed);
+* Combines the failures of two alternatives: the furthest failure wins, and
+* failures at the same offset have their expectations merged.
+*
+* @internal
+*/
+const mergeFailures = (a, b) => {
+	if (a.offset > b.offset) return a;
+	if (b.offset > a.offset) return b;
+	const expected = mergeExpected(a.expected, b.expected);
+	if (expected === b.expected) return b;
+	return new Failure(b.offset, b.kind, expected, b.context.length > 0 ? b.context : a.context, b.hasCause || a.hasCause, b.hasCause ? b.cause : a.cause, b.message ?? a.message, b.needed);
 };
+//#endregion
+export { Fail, Failure, State, emptyStrings, fromSource, mergeExpected, mergeFailures };
+
 //# sourceMappingURL=Input.js.map