tarsec 0.4.7 → 0.5.1

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.4.7",
+  "version": "0.5.1",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -24,6 +24,11 @@
       "import": "./dist/parsers/markdown/index.js",
       "require": "./dist/parsers/markdown/index.js",
       "types": "./dist/parsers/markdown/index.d.ts"
+    },
+    "./parsers/bash": {
+      "import": "./dist/parsers/bash/index.js",
+      "require": "./dist/parsers/bash/index.js",
+      "types": "./dist/parsers/bash/index.d.ts"
     }
   },
   "type": "module",