tarsec 0.5.0 → 0.5.1

package/dist/combinators.d.ts

@@ -65,6 +65,30 @@ export declare function many1WithJoin(parser: Parser<string>): Parser<string>;
  * @returns - a parser that tries each parser in order. Returns the result of the first parser that succeeds.
  */
 export declare function or<const T extends readonly GeneralParser<any, any>[]>(...parsers: T): PickParserType<T>;
+/**
+ * Commit point: once `prefix` succeeds, the branch is committed — a
+ * failure of `rest` is marked `committed` and stops backtracking. `or()`
+ * returns it instead of trying later alternatives, `many`/`optional`
+ * fail through it, `label` passes it along untouched, and lookahead
+ * (`not`, `peek`) contains it. A failure of `prefix` itself remains an
+ * ordinary, backtrackable failure.
+ *
+ * Use it where a prefix uniquely identifies a construct, so errors in
+ * the construct's body are reported as such instead of being drowned
+ * out by other alternatives' complaints:
+ *
+ * @example
+ * ```ts
+ * const codeLiteral = committed(str("[|"), literalBody);
+ * // On "[|broken", the error is literalBody's — no other parser in an
+ * // enclosing or() gets to reinterpret the text.
+ * ```
+ *
+ * @param prefix - parser identifying the construct; its result is discarded
+ * @param rest - parser for the remainder of the construct
+ * @returns a parser producing `rest`'s result
+ */
+export declare function committed<T>(prefix: Parser<unknown>, rest: Parser<T>): Parser<T>;
 /**
  * Takes a parser and runs it. If the parser fails,
  * optional returns a success with a null result.
@@ -307,6 +331,20 @@ export declare function many1Till<T>(parser: Parser<T>): Parser<string>;
 export declare function manyTillOneOf(stops: string[], { insensitive }?: {
     insensitive?: boolean;
 }): Parser<string>;
+/**
+ * Just like `manyTillOneOf`, but fails unless at least one character of
+ * input is consumed. Use this as the bulk "inert text" alternative inside
+ * an `or()` of chunk parsers: when a stop character is at the current
+ * position, this parser fails and `or()` moves on to the alternatives
+ * that know how to handle it.
+ *
+ * @param stops - the strings to stop at
+ * @param options - object of optional parameters. { insensitive: boolean }
+ * @returns a parser that consumes at least one character, up to a stop
+ */
+export declare function many1TillOneOf(stops: string[], { insensitive }?: {
+    insensitive?: boolean;
+}): Parser<string>;
 /**
  * `manyTillStr` is an optimized version of `manyTill`.
  * The `manyTill` combinator is slow because it runs the given parser
@@ -328,6 +366,53 @@ export declare function manyTillStr(str: string, { insensitive }?: {
  * @returns a parser that consumes the input string until the given string is found.
  */
 export declare function iManyTillStr(str: string): Parser<string>;
+/**
+ * Runs `parser` and discards its structured result, producing the raw
+ * text it consumed instead. The slice is taken from the input by length
+ * arithmetic — escapes and whitespace come back exactly as written, and
+ * no intermediate strings are built.
+ *
+ * @example
+ * ```ts
+ * const number = matchedText(many1(digit));
+ * number("123abc"); // success("123", "abc")
+ * ```
+ *
+ * @param parser - the parser whose consumed text to return
+ * @returns a parser producing the exact consumed slice
+ */
+export declare function matchedText(parser: Parser<unknown>): Parser<string>;
+/**
+ * Repeats `chunk` until `terminator` succeeds. The terminator is tried
+ * FIRST each round and is NOT consumed — parsing resumes at its start.
+ * Fails if the input ends before the terminator appears, if a chunk
+ * fails mid-scan, or if a chunk succeeds without consuming input (which
+ * would otherwise loop forever).
+ *
+ * Unlike `manyTill` (which scans character-by-character for a stop
+ * parser), `repeatTill` parses structured chunks — so regions where the
+ * terminator text is inert (strings, comments) can be skipped by making
+ * them chunks. For raw text output, wrap in `matchedText`. For speed,
+ * make the first chunk alternative a `many1TillOneOf` of every character
+ * that can begin a chunk or the terminator — it swallows runs of inert
+ * text in one indexOf-driven step.
+ *
+ * @example
+ * ```ts
+ * const bodyChunk = or(
+ *   many1TillOneOf(['"', "/", "|"]), // bulk inert text — caller's triggers
+ *   stringParser,                    // terminator inside a string is inert
+ *   commentParser,
+ *   anyChar,                         // lone trigger char that started nothing
+ * );
+ * const bodyText = matchedText(repeatTill(bodyChunk, str("|]")));
+ * ```
+ *
+ * @param chunk - parser for one repeated unit
+ * @param terminator - parser marking the end of the repetition (not consumed)
+ * @returns a parser producing the array of chunk results
+ */
+export declare function repeatTill<T>(chunk: Parser<T>, terminator: Parser<unknown>): Parser<T[]>;
 /**
  * `map` is a parser combinator that takes a parser and a mapper function.
  * If the parser succeeds, it maps its result using the mapper function.
@@ -501,9 +586,10 @@ export type OperatorInfo<T> = {
  */
 export declare function buildExpressionParser<T>(atom: Parser<T>, operatorTable: OperatorInfo<T>[][], parenParser?: Parser<T>): Parser<T>;
 /**
- * Clear every cache created by `memo`. Call this at the start of each
+ * Clear the current parse's memo caches. Call this at the start of each
  * top-level parse if your memoized parsers produce results that depend
  * on mutable global state (e.g. positional info from `setInputStr`).
+ * (`runNested` gives nested parses fresh caches automatically.)
  */
 export declare function resetMemos(): void;
 /**

package/dist/combinators.js

@@ -1,8 +1,20 @@
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
 import { within } from "./parsers/within.js";
 import { TarsecError } from "./tarsecError.js";
 import { getDiagnostics, trace } from "./trace.js";
-import { captureSuccess, failure, isCaptureResult, isSuccess, success, } from "./types.js";
+import { captureSuccess, failure, isCaptureResult, isCommittedFailure, isSuccess, success, } from "./types.js";
 import { escape } from "./utils.js";
+import { getParseState } from "./parseState.js";
 /**
  * Takes a parser and runs it zero or more times, returning the results as an array.
  * If the parser is a capture parser, it returns the captures as an array in this form:
@@ -25,6 +37,9 @@ export function many(parser) {
         while (true) {
             let parsed = parser(rest);
             if (!parsed.success) {
+                if (isCommittedFailure(parsed)) {
+                    return parsed; // committed: fail the whole repetition
+                }
                 if (Object.keys(captures).length) {
                     return captureSuccess(results, rest, { captures });
                 }
@@ -60,6 +75,9 @@ export function many(parser) {
 export function many1(parser) {
     return trace(`many1`, (input) => {
         let result = many(parser)(input);
+        if (!result.success && isCommittedFailure(result)) {
+            return result;
+        }
         // this logic doesn't work with optional and not
         if (result.rest !== input) {
             return result;
@@ -102,6 +120,9 @@ export function exactly(num, parser) {
         for (let i = 0; i < num; i++) {
             let parsed = parser(rest);
             if (!parsed.success) {
+                if (isCommittedFailure(parsed)) {
+                    return parsed;
+                }
                 return failure(`expected ${num} matches, got ${i}`, input);
             }
             results.push(parsed.result);
@@ -161,10 +182,53 @@ export function or(...parsers) {
             if (result.success) {
                 return result;
             }
+            if (isCommittedFailure(result)) {
+                return result; // committed: do not try later alternatives
+            }
         }
         return failure(`all parsers failed`, input);
     });
 }
+/**
+ * Commit point: once `prefix` succeeds, the branch is committed — a
+ * failure of `rest` is marked `committed` and stops backtracking. `or()`
+ * returns it instead of trying later alternatives, `many`/`optional`
+ * fail through it, `label` passes it along untouched, and lookahead
+ * (`not`, `peek`) contains it. A failure of `prefix` itself remains an
+ * ordinary, backtrackable failure.
+ *
+ * Use it where a prefix uniquely identifies a construct, so errors in
+ * the construct's body are reported as such instead of being drowned
+ * out by other alternatives' complaints:
+ *
+ * @example
+ * ```ts
+ * const codeLiteral = committed(str("[|"), literalBody);
+ * // On "[|broken", the error is literalBody's — no other parser in an
+ * // enclosing or() gets to reinterpret the text.
+ * ```
+ *
+ * @param prefix - parser identifying the construct; its result is discarded
+ * @param rest - parser for the remainder of the construct
+ * @returns a parser producing `rest`'s result
+ */
+export function committed(prefix, rest) {
+    return trace("committed", (input) => {
+        const prefixResult = prefix(input);
+        if (!prefixResult.success)
+            return prefixResult;
+        const restResult = rest(prefixResult.rest);
+        if (!restResult.success) {
+            const committedResult = Object.assign(Object.assign({}, restResult), { committed: true });
+            // Preferred slot for error reporting: getErrorMessage returns this
+            // in preference to the rightmost record, so a fallback alternative
+            // that wanders deeper than the commit point can't win the message.
+            getParseState().committedFailure = committedResult;
+            return committedResult;
+        }
+        return restResult;
+    });
+}
 /**
  * Takes a parser and runs it. If the parser fails,
  * optional returns a success with a null result.
@@ -179,6 +243,9 @@ export function optional(parser) {
         if (result.success) {
             return result;
         }
+        if (isCommittedFailure(result)) {
+            return result; // committed: not "optionally absent" — genuinely broken
+        }
         return success(null, input);
     });
 }
@@ -194,7 +261,11 @@ export function optional(parser) {
  */
 export function not(parser) {
     return trace("not", (input) => {
+        // The probe is speculation: a commit inside it must not escape,
+        // either through the result or through the committedFailure slot.
+        const slotBefore = getParseState().committedFailure;
         let result = parser(input);
+        getParseState().committedFailure = slotBefore;
         if (result.success) {
             return {
                 success: false,
@@ -207,9 +278,14 @@ export function not(parser) {
 }
 export function peek(parser) {
     return trace("peek", (input) => {
+        // The probe is speculation: contain any commit inside it — restore
+        // the slot and strip the flag, keeping peek's rest-reset contract.
+        const slotBefore = getParseState().committedFailure;
         const result = parser(input);
+        getParseState().committedFailure = slotBefore;
         if (!result.success) {
-            return Object.assign(Object.assign({}, result), { rest: input });
+            const { committed: _stripped } = result, plain = __rest(result, ["committed"]);
+            return Object.assign(Object.assign({}, plain), { rest: input });
         }
         return Object.assign(Object.assign({}, result), { rest: input });
     });
@@ -265,6 +341,9 @@ export function between(open, close, parser) {
             // the parser should keep succeeding until we find the closer
             // if it doesn't, we fail
             if (!parserResult.success) {
+                if (isCommittedFailure(parserResult)) {
+                    return parserResult; // committed: pass through unwrapped
+                }
                 return failure(parserResult.message, input);
             }
             successResult.push(parserResult.result);
@@ -308,12 +387,18 @@ export function sepBy(separator, parser) {
         while (true) {
             const result = parser(rest);
             if (!result.success) {
+                if (isCommittedFailure(result)) {
+                    return result; // committed: fail the whole sepBy
+                }
                 return success(results, rest);
             }
             results.push(result.result);
             rest = result.rest;
             const sepResult = separator(rest);
             if (!sepResult.success) {
+                if (isCommittedFailure(sepResult)) {
+                    return sepResult;
+                }
                 return success(results, rest);
             }
             rest = sepResult.rest;
@@ -478,14 +563,18 @@ export function captureCaptures(parser) {
  */
 export function manyTill(parser) {
     return (input) => {
+        // The stop probes are speculative; contain any commit they stash.
+        const slotBefore = getParseState().committedFailure;
         let current = 0;
         while (current < input.length) {
             const parsed = parser(input.slice(current));
             if (parsed.success) {
+                getParseState().committedFailure = slotBefore;
                 return success(input.slice(0, current), input.slice(current));
             }
             current++;
         }
+        getParseState().committedFailure = slotBefore;
         return success(input, "");
     };
 }
@@ -496,10 +585,13 @@ export function manyTill(parser) {
  */
 export function many1Till(parser) {
     return (input) => {
+        // The stop probes are speculative; contain any commit they stash.
+        const slotBefore = getParseState().committedFailure;
         let current = 0;
         while (current < input.length) {
             const parsed = parser(input.slice(current));
             if (parsed.success) {
+                getParseState().committedFailure = slotBefore;
                 if (current === 0) {
                     return failure("expected to consume at least one character of input", input);
                 }
@@ -507,6 +599,7 @@ export function many1Till(parser) {
             }
             current++;
         }
+        getParseState().committedFailure = slotBefore;
         if (current === 0) {
             return failure("expected to consume at least one character of input", input);
         }
@@ -546,6 +639,27 @@ export function manyTillOneOf(stops, { insensitive = false } = {}) {
         return success(input.slice(0, min), input.slice(min));
     });
 }
+/**
+ * Just like `manyTillOneOf`, but fails unless at least one character of
+ * input is consumed. Use this as the bulk "inert text" alternative inside
+ * an `or()` of chunk parsers: when a stop character is at the current
+ * position, this parser fails and `or()` moves on to the alternatives
+ * that know how to handle it.
+ *
+ * @param stops - the strings to stop at
+ * @param options - object of optional parameters. { insensitive: boolean }
+ * @returns a parser that consumes at least one character, up to a stop
+ */
+export function many1TillOneOf(stops, { insensitive = false } = {}) {
+    const scan = manyTillOneOf(stops, { insensitive });
+    return trace(`many1TillOneOf(${escape(stops.join(","))})`, (input) => {
+        const result = scan(input);
+        if (result.success && result.result.length === 0) {
+            return failure("expected to consume at least one character of input", input);
+        }
+        return result;
+    });
+}
 /**
  * `manyTillStr` is an optimized version of `manyTill`.
  * The `manyTill` combinator is slow because it runs the given parser
@@ -571,6 +685,90 @@ export function manyTillStr(str, { insensitive = false } = {}) {
 export function iManyTillStr(str) {
     return manyTillStr(str, { insensitive: true });
 }
+/**
+ * Runs `parser` and discards its structured result, producing the raw
+ * text it consumed instead. The slice is taken from the input by length
+ * arithmetic — escapes and whitespace come back exactly as written, and
+ * no intermediate strings are built.
+ *
+ * @example
+ * ```ts
+ * const number = matchedText(many1(digit));
+ * number("123abc"); // success("123", "abc")
+ * ```
+ *
+ * @param parser - the parser whose consumed text to return
+ * @returns a parser producing the exact consumed slice
+ */
+export function matchedText(parser) {
+    return trace("matchedText", (input) => {
+        const result = parser(input);
+        if (!result.success)
+            return result;
+        // Invariant (shared with withSpan): a parser's `rest` is a suffix of
+        // its input, so the consumed length is the difference of lengths.
+        const consumedLength = input.length - result.rest.length;
+        return success(input.slice(0, consumedLength), result.rest);
+    });
+}
+/**
+ * Repeats `chunk` until `terminator` succeeds. The terminator is tried
+ * FIRST each round and is NOT consumed — parsing resumes at its start.
+ * Fails if the input ends before the terminator appears, if a chunk
+ * fails mid-scan, or if a chunk succeeds without consuming input (which
+ * would otherwise loop forever).
+ *
+ * Unlike `manyTill` (which scans character-by-character for a stop
+ * parser), `repeatTill` parses structured chunks — so regions where the
+ * terminator text is inert (strings, comments) can be skipped by making
+ * them chunks. For raw text output, wrap in `matchedText`. For speed,
+ * make the first chunk alternative a `many1TillOneOf` of every character
+ * that can begin a chunk or the terminator — it swallows runs of inert
+ * text in one indexOf-driven step.
+ *
+ * @example
+ * ```ts
+ * const bodyChunk = or(
+ *   many1TillOneOf(['"', "/", "|"]), // bulk inert text — caller's triggers
+ *   stringParser,                    // terminator inside a string is inert
+ *   commentParser,
+ *   anyChar,                         // lone trigger char that started nothing
+ * );
+ * const bodyText = matchedText(repeatTill(bodyChunk, str("|]")));
+ * ```
+ *
+ * @param chunk - parser for one repeated unit
+ * @param terminator - parser marking the end of the repetition (not consumed)
+ * @returns a parser producing the array of chunk results
+ */
+export function repeatTill(chunk, terminator) {
+    return trace("repeatTill", (input) => {
+        const results = [];
+        let rest = input;
+        // Terminates: every iteration either returns or strictly shrinks
+        // `rest` (the progress guard below enforces it, even against a
+        // misbehaving chunk that returns a longer rest), and empty `rest`
+        // returns — at most input.length + 1 iterations.
+        while (true) {
+            const terminatorResult = terminator(rest);
+            if (terminatorResult.success) {
+                return success(results, rest);
+            }
+            if (rest.length === 0) {
+                return failure("input ended before terminator", rest);
+            }
+            const chunkResult = chunk(rest);
+            if (!chunkResult.success) {
+                return chunkResult;
+            }
+            if (chunkResult.rest.length >= rest.length) {
+                return failure("repeatTill chunk succeeded without consuming input", rest);
+            }
+            results.push(chunkResult.result);
+            rest = chunkResult.rest;
+        }
+    });
+}
 /**
  * `map` is a parser combinator that takes a parser and a mapper function.
  * If the parser succeeds, it maps its result using the mapper function.
@@ -651,6 +849,9 @@ export function seq(parsers, transform, debugName = "") {
         for (let i = 0; i < parsers.length; i++) {
             const parsed = parsers[i](rest);
             if (!parsed.success) {
+                if (isCommittedFailure(parsed)) {
+                    return parsed; // committed: keep the flag AND the failure position
+                }
                 return Object.assign(Object.assign({}, parsed), { rest: input });
             }
             results.push(parsed.result);
@@ -847,8 +1048,11 @@ export function buildExpressionParser(atom, operatorTable, parenParser) {
             if (!openResult.success)
                 return openResult;
             const exprResult = expr(openResult.rest);
-            if (!exprResult.success)
+            if (!exprResult.success) {
+                if (isCommittedFailure(exprResult))
+                    return exprResult;
                 return failure(exprResult.message, input);
+            }
             const closeResult = exprResult.rest[0] === ")" ? success(")", exprResult.rest.slice(1)) : failure("expected )", input);
             if (!closeResult.success)
                 return closeResult;
@@ -889,6 +1093,10 @@ function buildLevel(nextLevel, ops) {
     };
 }
 function parseLeft(left, rest, nextLevel, ops) {
+    // The fold's probes are speculative: a failing operator or operand just
+    // ends the chain. Discarding the failure must also discard any commit
+    // it stashed, or the stale slot would mask later errors' messages.
+    const slotBefore = getParseState().committedFailure;
     while (true) {
         const opMatch = tryOps(ops, rest);
         if (!opMatch)
@@ -899,21 +1107,28 @@ function parseLeft(left, rest, nextLevel, ops) {
         left = opMatch.apply(left, rightResult.result);
         rest = rightResult.rest;
     }
+    getParseState().committedFailure = slotBefore;
     return success(left, rest);
 }
 function parseRight(left, rest, nextLevel, ops) {
+    // Same speculative-probe containment as parseLeft.
+    const slotBefore = getParseState().committedFailure;
     const opMatch = tryOps(ops, rest);
     if (!opMatch)
         return success(left, rest);
     const rightResult = nextLevel(opMatch.rest);
-    if (!rightResult.success)
+    if (!rightResult.success) {
+        getParseState().committedFailure = slotBefore;
         return success(left, rest);
+    }
     // Recursively parse the right side to get right-associativity
     const rightFolded = parseRight(rightResult.result, rightResult.rest, nextLevel, ops);
     return success(opMatch.apply(left, rightFolded.result), rightFolded.rest);
 }
 function parseChain(left, rest, nextLevel, ops) {
     // Fallback: treat everything as left-associative
+    // Same speculative-probe containment as parseLeft.
+    const slotBefore = getParseState().committedFailure;
     while (true) {
         const opMatch = tryOps(ops, rest);
         if (!opMatch)
@@ -924,11 +1139,15 @@ function parseChain(left, rest, nextLevel, ops) {
         left = opMatch.apply(left, rightResult.result);
         rest = rightResult.rest;
     }
+    getParseState().committedFailure = slotBefore;
     return success(left, rest);
 }
 function tryOps(ops, input) {
+    // Op probes are speculative; contain any commit they stash.
+    const slotBefore = getParseState().committedFailure;
     for (const op of ops) {
         const result = op.op(input);
+        getParseState().committedFailure = slotBefore;
         if (result.success) {
             return { rest: result.rest, apply: op.apply };
         }
@@ -936,26 +1155,32 @@ function tryOps(ops, input) {
     return null;
 }
 const DEFAULT_MEMO_LIMIT = 10000;
-// Registry of all caches created by `memo`, so callers can clear them
-// between independent parses. This matters when memoized parsers produce
-// results derived from globally-set state (e.g. `withSpan` reads the
+// Caches created by `memo` live on the current parse state, keyed by a
+// per-memo numeric id. This matters when memoized parsers produce
+// results derived from the parse's state (e.g. `withSpan` reads the
 // current input via `setInputStr`): the cached `loc` is only valid for
-// the source it was computed against, so reusing the cache across parses
-// with different sources would return stale positional info.
-const memoCaches = [];
+// the source it was computed against, so a nested parse must never see
+// (or pollute) the enclosing parse's entries — swapping the state swaps
+// the caches with it.
+let nextMemoId = 0;
 /**
- * Clear every cache created by `memo`. Call this at the start of each
+ * Clear the current parse's memo caches. Call this at the start of each
  * top-level parse if your memoized parsers produce results that depend
  * on mutable global state (e.g. positional info from `setInputStr`).
+ * (`runNested` gives nested parses fresh caches automatically.)
  */
 export function resetMemos() {
-    for (const cache of memoCaches)
-        cache.clear();
+    getParseState().memoCaches.clear();
 }
 export function memo(name, parser) {
-    const cache = new Map();
-    memoCaches.push(cache);
+    const memoId = nextMemoId++;
     return trace(name ? `memo(${name})` : "memo", (input) => {
+        const state = getParseState();
+        let cache = state.memoCaches.get(memoId);
+        if (cache === undefined) {
+            cache = new Map();
+            state.memoCaches.set(memoId, cache);
+        }
         const hit = cache.get(input);
         if (hit !== undefined)
             return hit;

package/dist/index.d.ts

@@ -6,3 +6,5 @@ export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
 export * from "./lexeme.js";
+export * from "./parseState.js";
+export * from "./runNested.js";

package/dist/index.js

@@ -6,3 +6,5 @@ export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
 export * from "./lexeme.js";
+export * from "./parseState.js";
+export * from "./runNested.js";

package/dist/parseState.d.ts

@@ -0,0 +1,25 @@
+import type { Position } from "./position.js";
+import type { ParserFailure, ParserResult } from "./types.js";
+/**
+ * All mutable state belonging to one running parse. Everything tarsec
+ * used to keep in scattered module-level variables lives here, so a
+ * nested parse (see `runNested`) can swap in a fresh state and restore
+ * the old one by reassigning a single reference.
+ */
+export type ParseState = {
+    inputStr: string;
+    rightmostFailurePos: number;
+    rightmostFailureExpected: string[];
+    /** Per-`memo`-instance caches, keyed by each memo's numeric id. */
+    memoCaches: Map<number, Map<string, ParserResult<any>>>;
+    /** Offset added to every derived position, so a nested parse reports
+     *  positions in the enclosing parse's coordinates. Zero at top level. */
+    basePosition: Position;
+    /** The most recent committed failure of this parse, if any. Preferred
+     *  over the rightmost record by `getErrorMessage`. See `committed`. */
+    committedFailure: ParserFailure | null;
+};
+export declare function createParseState(inputStr: string, basePosition?: Position): ParseState;
+export declare function getParseState(): ParseState;
+/** Replace the current parse state, returning the previous one. */
+export declare function swapParseState(next: ParseState): ParseState;

package/dist/parseState.js

@@ -0,0 +1,21 @@
+const ZERO_POSITION = { offset: 0, line: 0, column: 0 };
+export function createParseState(inputStr, basePosition = ZERO_POSITION) {
+    return {
+        inputStr,
+        rightmostFailurePos: -1,
+        rightmostFailureExpected: [],
+        memoCaches: new Map(),
+        basePosition: Object.assign({}, basePosition),
+        committedFailure: null,
+    };
+}
+let currentState = createParseState("");
+export function getParseState() {
+    return currentState;
+}
+/** Replace the current parse state, returning the previous one. */
+export function swapParseState(next) {
+    const previous = currentState;
+    currentState = next;
+    return previous;
+}

package/dist/parsers/within.js

@@ -1,5 +1,6 @@
 import { trace } from "../trace.js";
 import { success } from "../types.js";
+import { getParseState } from "../parseState.js";
 /**
  * `within` is a funny combinator. It finds zero or more instances of `parser` within the input.
  * It always succeeds and returns an array of results, each one being a matched or unmatched string.
@@ -59,6 +60,9 @@ import { success } from "../types.js";
  */
 export function within(parser) {
     return trace("within", (input) => {
+        // A search is speculation: probes at every offset must not leak
+        // commits into the committedFailure slot.
+        const slotBefore = getParseState().committedFailure;
         let start = 0;
         let current = 0;
         const results = [];
@@ -89,6 +93,7 @@ export function within(parser) {
                 value: input.slice(start, current),
             });
         }
+        getParseState().committedFailure = slotBefore;
         return success(results, "");
     });
 }

package/dist/parsers.d.ts

@@ -138,8 +138,19 @@ export declare function takeWhile1(charsOrPred: string | CharPredicate, expected
 export declare const anyChar: Parser<string>;
 /**
  * Wraps a parser with a human-readable label for error reporting.
- * On failure, suppresses any inner failure recordings and records only the label.
- * This produces clean error messages like `expected a digit` instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails at the label's own position (it never got
+ * anywhere), its internal failure records are suppressed and only the
+ * label is recorded — producing clean messages like `expected a digit`
+ * instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails STRICTLY INSIDE the labeled region (it
+ * consumed input first), its deeper, more specific record is kept and
+ * the label stays out of the way — so a grammar labeled at every level
+ * still surfaces the deepest thing the parser actually knew.
+ * (Comparing against the label's own position, rather than the previous
+ * record, is what keeps shallow labels clean while deep knowledge
+ * survives.)
  *
  * @param name - human-readable description of what the parser expects
  * @param parser - the parser to wrap

package/dist/parsers.js

@@ -1,5 +1,5 @@
 import { many1WithJoin } from "./combinators.js";
-import { trace } from "./trace.js";
+import { trace, getInputStr } from "./trace.js";
 import { recordFailure, saveRightmostFailure, restoreRightmostFailure } from "./rightmostFailure.js";
 import { captureSuccess, failure, success, } from "./types.js";
 import { escape } from "./utils.js";
@@ -241,8 +241,19 @@ export const anyChar = trace("anyChar", (input) => {
 });
 /**
  * Wraps a parser with a human-readable label for error reporting.
- * On failure, suppresses any inner failure recordings and records only the label.
- * This produces clean error messages like `expected a digit` instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails at the label's own position (it never got
+ * anywhere), its internal failure records are suppressed and only the
+ * label is recorded — producing clean messages like `expected a digit`
+ * instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails STRICTLY INSIDE the labeled region (it
+ * consumed input first), its deeper, more specific record is kept and
+ * the label stays out of the way — so a grammar labeled at every level
+ * still surfaces the deepest thing the parser actually knew.
+ * (Comparing against the label's own position, rather than the previous
+ * record, is what keeps shallow labels clean while deep knowledge
+ * survives.)
  *
  * @param name - human-readable description of what the parser expects
  * @param parser - the parser to wrap
@@ -252,6 +263,21 @@ export function label(name, parser) {
     return (input) => {
         const saved = saveRightmostFailure();
         const result = parser(input);
+        if (!result.success && result.committed === true) {
+            // Committed failures carry their own story — no re-labeling,
+            // no restore games.
+            return result;
+        }
+        const afterChild = saveRightmostFailure();
+        const labelPos = getInputStr().length - input.length;
+        const childGotStrictlyDeeper = afterChild.pos > labelPos;
+        if (!result.success && childGotStrictlyDeeper) {
+            // The child FAILED somewhere specific past this label's start —
+            // keep its record; adding the label here would only blur it.
+            // On success the restore below still runs, scrubbing speculative
+            // records left by backtracked alternatives inside the region.
+            return result;
+        }
         restoreRightmostFailure(saved);
         if (!result.success)
             recordFailure(input, name);

package/dist/position.d.ts

@@ -18,14 +18,24 @@ export declare function buildLineTable(source: string): number[];
  * Both line and column are 0-based.
  */
 export declare function offsetToPosition(lineTable: number[], offset: number): Position;
+/**
+ * Compose an inner-parse position with a base position (the point in the
+ * enclosing input where the inner input begins). Offsets and lines add;
+ * the base column applies only while still on the base line (inner line 0).
+ */
+export declare function composePosition(base: Position, pos: Position): Position;
 /**
  * A zero-width parser that returns the current offset into the input string.
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the offset is reported in the enclosing parse's
+ * coordinates (the state's `basePosition` is added).
  */
 export declare const getOffset: Parser<number>;
 /**
  * A zero-width parser that returns the current position (offset, line, column).
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the position is reported in the enclosing parse's
+ * coordinates (composed with the state's `basePosition`).
  */
 export declare const getPosition: Parser<Position>;
 /**

package/dist/position.js

@@ -1,5 +1,9 @@
-import { getInputStr } from "./trace.js";
+// NOTE: this module deliberately imports nothing from trace.ts — it reads
+// the input via getParseState().inputStr. trace.ts imports composePosition
+// from here, so an import in the other direction would create a runtime
+// module cycle (fragile TDZ hazard under refactoring/bundlers).
 import { success } from "./types.js";
+import { getParseState } from "./parseState.js";
 /**
  * Build a lookup table of line-start offsets for a given source string.
  * This allows O(log n) offset-to-position conversion via binary search.
@@ -17,6 +21,9 @@ export function buildLineTable(source) {
 // table on every invocation. Parses run sequentially with a single
 // `setInputStr` source, so a most-recently-seen cache is sufficient and
 // avoids O(num_calls * source.length) work during a parse.
+// Deliberately NOT part of ParseState: keyed by source-string identity,
+// so a nested parse's source misses and rebuilds — it can never serve a
+// stale table across parse states.
 let cachedSource = null;
 let cachedLineTable = [0];
 function getLineTable(source) {
@@ -49,23 +56,45 @@ export function offsetToPosition(lineTable, offset) {
         column: offset - lineTable[lo],
     };
 }
+/**
+ * Compose an inner-parse position with a base position (the point in the
+ * enclosing input where the inner input begins). Offsets and lines add;
+ * the base column applies only while still on the base line (inner line 0).
+ */
+export function composePosition(base, pos) {
+    if (base.offset === 0 && base.line === 0 && base.column === 0) {
+        return pos;
+    }
+    const column = pos.line === 0 ? base.column + pos.column : pos.column;
+    return {
+        offset: base.offset + pos.offset,
+        line: base.line + pos.line,
+        column,
+    };
+}
 /**
  * A zero-width parser that returns the current offset into the input string.
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the offset is reported in the enclosing parse's
+ * coordinates (the state's `basePosition` is added).
  */
 export const getOffset = (input) => {
-    const source = getInputStr();
-    return success(source.length - input.length, input);
+    const source = getParseState().inputStr;
+    const base = getParseState().basePosition;
+    return success(base.offset + (source.length - input.length), input);
 };
 /**
  * A zero-width parser that returns the current position (offset, line, column).
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the position is reported in the enclosing parse's
+ * coordinates (composed with the state's `basePosition`).
  */
 export const getPosition = (input) => {
-    const source = getInputStr();
+    const source = getParseState().inputStr;
     const offset = source.length - input.length;
     const lineTable = getLineTable(source);
-    return success(offsetToPosition(lineTable, offset), input);
+    const base = getParseState().basePosition;
+    return success(composePosition(base, offsetToPosition(lineTable, offset)), input);
 };
 /**
  * Wraps a parser so that its result includes span information (start and end positions).
@@ -80,18 +109,19 @@ export const getPosition = (input) => {
  */
 export function withSpan(parser) {
     return (input) => {
-        const source = getInputStr();
+        const source = getParseState().inputStr;
         const lineTable = getLineTable(source);
         const startOffset = source.length - input.length;
         const result = parser(input);
         if (!result.success)
             return result;
         const endOffset = source.length - result.rest.length;
+        const base = getParseState().basePosition;
         return success({
             value: result.result,
             span: {
-                start: offsetToPosition(lineTable, startOffset),
-                end: offsetToPosition(lineTable, endOffset),
+                start: composePosition(base, offsetToPosition(lineTable, startOffset)),
+                end: composePosition(base, offsetToPosition(lineTable, endOffset)),
             },
         }, result.rest);
     };

package/dist/rightmostFailure.d.ts

@@ -25,6 +25,16 @@ export declare function saveRightmostFailure(): SavedRightmostFailure;
 export declare function restoreRightmostFailure(saved: SavedRightmostFailure): void;
 /**
  * Formats the rightmost failure into a human-readable error message with line and column info.
+ * A committed failure (see the `committed` combinator) takes precedence
+ * over the rightmost record — the committed error wins reporting even
+ * when some fallback alternative failed deeper into the input.
+ *
+ * Scope: the preference is per parse state. A commit inside `runNested`
+ * lives in the inner state and surfaces through the returned result's
+ * `committed` flag, never through the enclosing parse's getErrorMessage.
+ * The position math assumes the committed failure's `rest` is a suffix
+ * of the CURRENT state's source — don't stash a `runNested` result
+ * (inner-coordinate `rest`) into an outer-state commit.
  * Returns `null` if no failures have been recorded.
  * Requires `setInputStr` to have been called.
  */

package/dist/rightmostFailure.js

@@ -1,10 +1,11 @@
 import { getInputStr } from "./trace.js";
-import { buildLineTable, offsetToPosition } from "./position.js";
-let rightmostFailurePos = -1;
-let rightmostFailureExpected = [];
+import { buildLineTable, offsetToPosition, composePosition } from "./position.js";
+import { getParseState } from "./parseState.js";
 export function resetRightmostFailure() {
-    rightmostFailurePos = -1;
-    rightmostFailureExpected = [];
+    const state = getParseState();
+    state.rightmostFailurePos = -1;
+    state.rightmostFailureExpected = [];
+    state.committedFailure = null;
 }
 /**
  * Record an expected alternative at the current failure position.
@@ -16,17 +17,18 @@ export function resetRightmostFailure() {
  * @param expected - a human-readable description of what was expected
  */
 export function recordFailure(input, expected) {
+    const state = getParseState();
     const source = getInputStr();
     if (source.length === 0)
         return;
     const pos = source.length - input.length;
-    if (pos > rightmostFailurePos) {
-        rightmostFailurePos = pos;
-        rightmostFailureExpected = [expected];
+    if (pos > state.rightmostFailurePos) {
+        state.rightmostFailurePos = pos;
+        state.rightmostFailureExpected = [expected];
     }
-    else if (pos === rightmostFailurePos) {
-        if (!rightmostFailureExpected.includes(expected)) {
-            rightmostFailureExpected.push(expected);
+    else if (pos === state.rightmostFailurePos) {
+        if (!state.rightmostFailureExpected.includes(expected)) {
+            state.rightmostFailureExpected.push(expected);
         }
     }
 }
@@ -35,16 +37,25 @@ export function recordFailure(input, expected) {
  * or `null` if no failures have been recorded.
  */
 export function getRightmostFailure() {
-    if (rightmostFailurePos < 0)
+    const state = getParseState();
+    if (state.rightmostFailurePos < 0)
         return null;
-    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+    return {
+        pos: state.rightmostFailurePos,
+        expected: [...state.rightmostFailureExpected],
+    };
 }
 export function saveRightmostFailure() {
-    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+    const state = getParseState();
+    return {
+        pos: state.rightmostFailurePos,
+        expected: [...state.rightmostFailureExpected],
+    };
 }
 export function restoreRightmostFailure(saved) {
-    rightmostFailurePos = saved.pos;
-    rightmostFailureExpected = [...saved.expected];
+    const state = getParseState();
+    state.rightmostFailurePos = saved.pos;
+    state.rightmostFailureExpected = [...saved.expected];
 }
 function formatExpected(expected) {
     if (expected.length === 1)
@@ -55,16 +66,34 @@ function formatExpected(expected) {
 }
 /**
  * Formats the rightmost failure into a human-readable error message with line and column info.
+ * A committed failure (see the `committed` combinator) takes precedence
+ * over the rightmost record — the committed error wins reporting even
+ * when some fallback alternative failed deeper into the input.
+ *
+ * Scope: the preference is per parse state. A commit inside `runNested`
+ * lives in the inner state and surfaces through the returned result's
+ * `committed` flag, never through the enclosing parse's getErrorMessage.
+ * The position math assumes the committed failure's `rest` is a suffix
+ * of the CURRENT state's source — don't stash a `runNested` result
+ * (inner-coordinate `rest`) into an outer-state commit.
  * Returns `null` if no failures have been recorded.
  * Requires `setInputStr` to have been called.
  */
 export function getErrorMessage() {
-    if (rightmostFailurePos < 0)
+    const state = getParseState();
+    const committed = state.committedFailure;
+    if (committed !== null) {
+        const source = getInputStr();
+        const lineTable = buildLineTable(source);
+        const pos = composePosition(state.basePosition, offsetToPosition(lineTable, source.length - committed.rest.length));
+        return `Line ${pos.line + 1}, col ${pos.column + 1}: ${committed.message}`;
+    }
+    if (state.rightmostFailurePos < 0)
         return null;
     const source = getInputStr();
     const lineTable = buildLineTable(source);
-    const pos = offsetToPosition(lineTable, rightmostFailurePos);
+    const pos = composePosition(state.basePosition, offsetToPosition(lineTable, state.rightmostFailurePos));
     const line = pos.line + 1;
     const column = pos.column + 1;
-    return `Line ${line}, col ${column}: expected ${formatExpected(rightmostFailureExpected)}`;
+    return `Line ${line}, col ${column}: expected ${formatExpected(state.rightmostFailureExpected)}`;
 }

package/dist/runNested.d.ts

@@ -0,0 +1,24 @@
+import { Parser, ParserResult } from "./types.js";
+import type { Position } from "./position.js";
+export type NestedOptions = {
+    /** Positions in the sub-parse's results are offset by this, so spans
+     *  and error messages come out in the ENCLOSING parse's coordinates.
+     *  Defaults to zero (positions relative to `input`). */
+    basePosition?: Position;
+};
+/**
+ * Run a complete parse of `input` with its own input string, rightmost-
+ * failure record, and memo caches, restoring the enclosing parse's state
+ * on exit — success, failure, or throw. The one supported way to run a
+ * parse inside another parse.
+ *
+ * @example
+ * ```ts
+ * // While parsing a file, parse an embedded snippet as its own program,
+ * // reporting positions relative to the enclosing file:
+ * const embedded = runNested(exprParser, snippetText, {
+ *   basePosition: openingPosition, // where the snippet starts in the file
+ * });
+ * ```
+ */
+export declare function runNested<T>(parser: Parser<T>, input: string, opts?: NestedOptions): ParserResult<T>;

package/dist/runNested.js

@@ -0,0 +1,28 @@
+import { createParseState, swapParseState } from "./parseState.js";
+/**
+ * Run a complete parse of `input` with its own input string, rightmost-
+ * failure record, and memo caches, restoring the enclosing parse's state
+ * on exit — success, failure, or throw. The one supported way to run a
+ * parse inside another parse.
+ *
+ * @example
+ * ```ts
+ * // While parsing a file, parse an embedded snippet as its own program,
+ * // reporting positions relative to the enclosing file:
+ * const embedded = runNested(exprParser, snippetText, {
+ *   basePosition: openingPosition, // where the snippet starts in the file
+ * });
+ * ```
+ */
+export function runNested(parser, input, opts) {
+    // Deliberately does NOT call setInputStr: createParseState pre-sets
+    // inputStr and a fresh rightmost record (replicating setInputStr's
+    // reset), and calling it here would clobber the fresh state's fields.
+    const savedState = swapParseState(createParseState(input, opts === null || opts === void 0 ? void 0 : opts.basePosition));
+    try {
+        return parser(input);
+    }
+    finally {
+        swapParseState(savedState);
+    }
+}

package/dist/trace.js

@@ -2,6 +2,8 @@ import { escape, round, shorten } from "./utils.js";
 import process from "process";
 import { execSync } from "child_process";
 import { resetRightmostFailure } from "./rightmostFailure.js";
+import { getParseState } from "./parseState.js";
+import { composePosition } from "./position.js";
 const isNode = typeof process !== "undefined" &&
     process.versions != null &&
     process.versions.node != null;
@@ -186,7 +188,6 @@ export function limitSteps(limit, callback) {
     callback();
     stepLimit = -1;
 }
-let inputStr = "";
 /**
  * Use this function in conjunction with the parseError combinator. Before running your parser,
  * call this function, giving it the entire input. Then, if the parseError combinator throws an error,
@@ -194,11 +195,11 @@ let inputStr = "";
  * @param s full string to parse
  */
 export function setInputStr(s) {
-    inputStr = s;
+    getParseState().inputStr = s;
     resetRightmostFailure();
 }
 export function getInputStr() {
-    return inputStr;
+    return getParseState().inputStr;
 }
 export function getDiagnostics(result, input, _message) {
     const inputStr = getInputStr();
@@ -222,9 +223,14 @@ export function getDiagnostics(result, input, _message) {
         }
         const linesIndex = Math.max(0, i - 1);
         const column = lines[linesIndex].length - (acc - index);
-        return {
+        const composed = composePosition(getParseState().basePosition, {
+            offset: index,
             line: i - 1,
             column,
+        });
+        return {
+            line: composed.line,
+            column: composed.column,
             length: 1,
             prettyMessage: messages.join("\n"),
             message: message,

package/dist/types.d.ts

@@ -18,6 +18,11 @@ export type ParserFailure = {
     success: false;
     rest: string;
     message: string;
+    /** Set when the failure occurred past a commit point (see `committed`).
+     *  Backtracking combinators (`or`, `many`, `optional`) propagate a
+     *  committed failure instead of trying alternatives; lookahead
+     *  combinators (`not`, `peek`) contain it. */
+    committed?: true;
 };
 export type ParserResult<T> = ParserSuccess<T> | ParserFailure;
 export type CaptureParserResult<T, C extends PlainObject> = CaptureParserSuccess<T, C> | ParserFailure;
@@ -50,6 +55,14 @@ export declare function success<T>(result: T, rest: string): ParserSuccess<T>;
 export declare function captureSuccess<T, C extends PlainObject>(result: T, rest: string, captures: C): CaptureParserSuccess<T, C>;
 /** Convenience function to return a ParserFailure */
 export declare function failure(message: string, rest: string): ParserFailure;
+/** Convenience function to return a committed ParserFailure — a failure
+ *  that stops backtracking. See the `committed` combinator. */
+export declare function committedFailure(message: string, rest: string): ParserFailure;
+/** True when the result is a failure that occurred past a commit point. */
+export declare function isCommittedFailure(result: {
+    success: boolean;
+    committed?: true;
+}): boolean;
 /** Prettify an intersected type, to make it easier to read. */
 export type Prettify<T> = {
     [K in keyof T]: T[K];

package/dist/types.js

@@ -30,3 +30,12 @@ export function captureSuccess(result, rest, captures) {
 export function failure(message, rest) {
     return { success: false, message, rest };
 }
+/** Convenience function to return a committed ParserFailure — a failure
+ *  that stops backtracking. See the `committed` combinator. */
+export function committedFailure(message, rest) {
+    return { success: false, message, rest, committed: true };
+}
+/** True when the result is a failure that occurred past a commit point. */
+export function isCommittedFailure(result) {
+    return !result.success && result.committed === true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {