tarsec 0.1.8 → 0.2.0

package/README.md

@@ -45,6 +45,7 @@ parser("hello there"); // failure
 - Tools to debug your parser's [performance](/tutorials/performance.md)
 - Partial [backtracking](/tutorials/backtracking.md) support
 - A way to make your parser more [secure](/tutorials/security.md).
+- [Pretty error messages](/tutorials/pretty-errors.md)
 
 ## Examples
 - [A markdown parser](/tests/examples/markdown.ts)

package/dist/combinators.d.ts

@@ -438,3 +438,55 @@ export declare function and<const T extends readonly GeneralParser<any, any>[]>(
  * @returns
  */
 export declare function parseError<const T extends readonly GeneralParser<any, any>[]>(_message: string, ...parsers: T): Parser<MergedCaptures<T>>;
+/**
+ * Defers evaluation of a parser, allowing recursive parser definitions.
+ * Without `lazy`, you can't reference a parser before it's defined:
+ *
+ * ```ts
+ * // ReferenceError: expr is not defined
+ * const expr = or(number, seqR(char("("), expr, char(")")));
+ *
+ * // Works: the reference to expr is deferred
+ * const expr = or(number, seqR(char("("), lazy(() => expr), char(")")));
+ * ```
+ *
+ * @param thunk - a function that returns the parser
+ * @returns - a parser that evaluates the thunk on each parse attempt
+ */
+export declare function lazy<T>(thunk: () => Parser<T>): Parser<T>;
+export type Associativity = "left" | "right";
+export type OperatorInfo<T> = {
+    /** A parser that matches the operator (e.g. `char("+")` or `str("**")`) */
+    op: Parser<any>;
+    /** Whether the operator is left- or right-associative */
+    assoc: Associativity;
+    /** A function that combines the left and right operands.
+     * For example: `(a, b) => a + b` */
+    apply: (left: T, right: T) => T;
+};
+/**
+ * Builds an expression parser that handles operator precedence and associativity.
+ * Operators are given as an array of precedence levels, from **highest** to **lowest**.
+ * Each level is an array of operators at that precedence.
+ *
+ * ```ts
+ * const expr = buildExpressionParser(
+ *   numberParser,
+ *   [
+ *     [{ op: char("*"), assoc: "left", apply: (a, b) => a * b },
+ *      { op: char("/"), assoc: "left", apply: (a, b) => a / b }],
+ *     [{ op: char("+"), assoc: "left", apply: (a, b) => a + b },
+ *      { op: char("-"), assoc: "left", apply: (a, b) => a - b }],
+ *   ],
+ *   // optional: override how parenthesized sub-expressions are parsed
+ *   // defaults to: seqR(char("("), lazy(() => expr), char(")")) mapped to the middle result
+ * );
+ * ```
+ *
+ * @param atom - parser for the smallest unit (numbers, identifiers, parenthesized sub-expressions)
+ * @param operatorTable - array of precedence levels, highest first. Each level is an array of OperatorInfo.
+ * @param parenParser - optional parser for parenthesized sub-expressions. If not provided,
+ *   one is built automatically using `(` and `)` with `lazy` to handle recursion.
+ * @returns - a parser that handles the full expression grammar
+ */
+export declare function buildExpressionParser<T>(atom: Parser<T>, operatorTable: OperatorInfo<T>[][], parenParser?: Parser<T>): Parser<T>;

package/dist/combinators.js

@@ -1,6 +1,6 @@
 import { within } from "./parsers/within.js";
 import { TarsecError } from "./tarsecError.js";
-import { getInputStr, trace } from "./trace.js";
+import { getDiagnostics, trace } from "./trace.js";
 import { captureSuccess, createTree, failure, isCaptureResult, isSuccess, success, } from "./types.js";
 import { escape, findAncestorWithNextParser, popMany } from "./utils.js";
 /**
@@ -871,47 +871,158 @@ export function parseError(_message, ...parsers) {
             return result;
         }
         else {
-            const inputStr = getInputStr();
-            const messages = [];
-            const prefix = "Near: ";
-            if (inputStr.length > 0) {
-                const index = inputStr.length - input.length;
-                const start = Math.max(0, index - 20);
-                const end = Math.min(inputStr.length, index + 20);
-                const previewStr = inputStr.substring(start, end).split("\n")[0];
-                messages.push(`${prefix}${previewStr}`);
-                messages.push(`${" ".repeat(index + prefix.length)}^`);
-                messages.push(_message);
-                const message = messages.join("\n");
-                const lines = inputStr.split("\n");
-                let acc = 0;
-                let i = 0;
-                while (index >= acc) {
-                    acc += lines[i].length;
-                    i++;
-                }
-                const linesIndex = Math.max(0, i - 1);
-                const column = lines[linesIndex].length - (acc - index);
-                throw new TarsecError({
-                    line: i - 1,
-                    column,
-                    length: 1,
-                    prettyMessage: message,
-                    message: _message,
-                });
-            }
-            else {
-                messages.push(`${prefix}${input.substring(1, 100)}`);
-                messages.push(_message);
-                const message = messages.join("\n");
-                throw new TarsecError({
-                    line: 0,
-                    column: 0,
-                    length: 0,
-                    prettyMessage: message,
-                    message: _message,
-                });
-            }
+            const error = getDiagnostics(result, input, _message);
+            throw new TarsecError(error);
+        }
+    };
+}
+/**
+ * Defers evaluation of a parser, allowing recursive parser definitions.
+ * Without `lazy`, you can't reference a parser before it's defined:
+ *
+ * ```ts
+ * // ReferenceError: expr is not defined
+ * const expr = or(number, seqR(char("("), expr, char(")")));
+ *
+ * // Works: the reference to expr is deferred
+ * const expr = or(number, seqR(char("("), lazy(() => expr), char(")")));
+ * ```
+ *
+ * @param thunk - a function that returns the parser
+ * @returns - a parser that evaluates the thunk on each parse attempt
+ */
+export function lazy(thunk) {
+    return trace("lazy", (input) => thunk()(input));
+}
+/**
+ * Builds an expression parser that handles operator precedence and associativity.
+ * Operators are given as an array of precedence levels, from **highest** to **lowest**.
+ * Each level is an array of operators at that precedence.
+ *
+ * ```ts
+ * const expr = buildExpressionParser(
+ *   numberParser,
+ *   [
+ *     [{ op: char("*"), assoc: "left", apply: (a, b) => a * b },
+ *      { op: char("/"), assoc: "left", apply: (a, b) => a / b }],
+ *     [{ op: char("+"), assoc: "left", apply: (a, b) => a + b },
+ *      { op: char("-"), assoc: "left", apply: (a, b) => a - b }],
+ *   ],
+ *   // optional: override how parenthesized sub-expressions are parsed
+ *   // defaults to: seqR(char("("), lazy(() => expr), char(")")) mapped to the middle result
+ * );
+ * ```
+ *
+ * @param atom - parser for the smallest unit (numbers, identifiers, parenthesized sub-expressions)
+ * @param operatorTable - array of precedence levels, highest first. Each level is an array of OperatorInfo.
+ * @param parenParser - optional parser for parenthesized sub-expressions. If not provided,
+ *   one is built automatically using `(` and `)` with `lazy` to handle recursion.
+ * @returns - a parser that handles the full expression grammar
+ */
+export function buildExpressionParser(atom, operatorTable, parenParser) {
+    // Build the parser from highest precedence to lowest.
+    // Each level wraps the previous one, so higher-precedence operators bind tighter.
+    // The "base" is the atom or a parenthesized expression.
+    // We use lazy for the paren parser since it references the final `expr` which doesn't exist yet.
+    let expr;
+    const base = (input) => {
+        const paren = parenParser !== null && parenParser !== void 0 ? parenParser : buildDefaultParenParser();
+        const result = paren(input);
+        if (result.success)
+            return result;
+        return atom(input);
+    };
+    function buildDefaultParenParser() {
+        return (input) => {
+            const openResult = input[0] === "(" ? success("(", input.slice(1)) : failure("expected (", input);
+            if (!openResult.success)
+                return openResult;
+            const exprResult = expr(openResult.rest);
+            if (!exprResult.success)
+                return failure(exprResult.message, input);
+            const closeResult = exprResult.rest[0] === ")" ? success(")", exprResult.rest.slice(1)) : failure("expected )", input);
+            if (!closeResult.success)
+                return closeResult;
+            return success(exprResult.result, closeResult.rest);
+        };
+    }
+    // Start with the base (atoms and parens), then wrap with each precedence level
+    let currentLevel = base;
+    for (let i = 0; i < operatorTable.length; i++) {
+        const ops = operatorTable[i];
+        currentLevel = buildLevel(currentLevel, ops);
+    }
+    expr = currentLevel;
+    return expr;
+}
+function buildLevel(nextLevel, ops) {
+    return (input) => {
+        const leftResult = nextLevel(input);
+        if (!leftResult.success)
+            return leftResult;
+        // Try to parse a chain of operators at this level
+        let left = leftResult.result;
+        let rest = leftResult.rest;
+        // For right-associative, we collect all operands and operators, then fold right
+        const rightOps = ops.filter((o) => o.assoc === "right");
+        const leftOps = ops.filter((o) => o.assoc === "left");
+        if (rightOps.length > 0 && leftOps.length > 0) {
+            // Mixed associativity at same level: handle left-assoc first in the loop,
+            // then right-assoc. This is an unusual case but we handle it.
+            return parseChain(left, rest, nextLevel, ops);
+        }
+        else if (rightOps.length > 0) {
+            return parseRight(left, rest, nextLevel, rightOps);
+        }
+        else {
+            return parseLeft(left, rest, nextLevel, leftOps);
         }
     };
 }
+function parseLeft(left, rest, nextLevel, ops) {
+    while (true) {
+        const opMatch = tryOps(ops, rest);
+        if (!opMatch)
+            break;
+        const rightResult = nextLevel(opMatch.rest);
+        if (!rightResult.success)
+            break;
+        left = opMatch.apply(left, rightResult.result);
+        rest = rightResult.rest;
+    }
+    return success(left, rest);
+}
+function parseRight(left, rest, nextLevel, ops) {
+    const opMatch = tryOps(ops, rest);
+    if (!opMatch)
+        return success(left, rest);
+    const rightResult = nextLevel(opMatch.rest);
+    if (!rightResult.success)
+        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
+    while (true) {
+        const opMatch = tryOps(ops, rest);
+        if (!opMatch)
+            break;
+        const rightResult = nextLevel(opMatch.rest);
+        if (!rightResult.success)
+            break;
+        left = opMatch.apply(left, rightResult.result);
+        rest = rightResult.rest;
+    }
+    return success(left, rest);
+}
+function tryOps(ops, input) {
+    for (const op of ops) {
+        const result = op.op(input);
+        if (result.success) {
+            return { rest: result.rest, apply: op.apply };
+        }
+    }
+    return null;
+}

package/dist/index.d.ts

@@ -3,3 +3,5 @@ export * from "./combinators.js";
 export * from "./trace.js";
 export * from "./types.js";
 export * from "./tarsecError.js";
+export * from "./position.js";
+export * from "./rightmostFailure.js";

package/dist/index.js

@@ -3,3 +3,5 @@ export * from "./combinators.js";
 export * from "./trace.js";
 export * from "./types.js";
 export * from "./tarsecError.js";
+export * from "./position.js";
+export * from "./rightmostFailure.js";

package/dist/parsers.d.ts

@@ -44,6 +44,16 @@ export declare function noneOf(chars: string): Parser<string>;
  * @returns - ParserResult
  */
 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"`.
+ *
+ * @param name - human-readable description of what the parser expects
+ * @param parser - the parser to wrap
+ * @returns - a parser that records the label on failure
+ */
+export declare function label<T>(name: string, parser: Parser<T>): Parser<T>;
 /** A parser that matches one of " \t\n\r". */
 export declare const space: Parser<string>;
 /** A parser that matches one or more spaces. */

package/dist/parsers.js

@@ -1,5 +1,6 @@
 import { many1WithJoin, manyWithJoin, seq } from "./combinators.js";
 import { trace } from "./trace.js";
+import { recordFailure, saveRightmostFailure, restoreRightmostFailure } from "./rightmostFailure.js";
 import { captureSuccess, failure, success, } from "./types.js";
 import { escape } from "./utils.js";
 export { within } from "./parsers/within.js";
@@ -12,15 +13,13 @@ export { within } from "./parsers/within.js";
 export function char(c) {
     return trace(`char(${escape(c)})`, (input) => {
         if (input.length === 0) {
-            return {
-                success: false,
-                rest: input,
-                message: "unexpected end of input",
-            };
+            recordFailure(input, `"${c}"`);
+            return failure("unexpected end of input", input);
         }
         if (input[0] === c) {
             return success(c, input.slice(1));
         }
+        recordFailure(input, `"${c}"`);
         return failure(`expected ${escape(c)}, got ${escape(input[0])}`, input);
     });
 }
@@ -35,6 +34,7 @@ export function str(s) {
         if (input.substring(0, s.length) === s) {
             return success(s, input.slice(s.length));
         }
+        recordFailure(input, `"${s}"`);
         return failure(`expected ${s}, got ${input.substring(0, s.length)}`, input);
     });
 }
@@ -48,6 +48,7 @@ export function istr(s) {
         if (input.substring(0, s.length).toLocaleLowerCase() === s.toLocaleLowerCase()) {
             return success(input.substring(0, s.length), input.slice(s.length));
         }
+        recordFailure(input, `"${s}"`);
         return failure(`expected ${s}, got ${input.substring(0, s.length)}`, input);
     });
 }
@@ -61,12 +62,14 @@ export function istr(s) {
 export function oneOf(chars) {
     return trace(`oneOf(${escape(chars)})`, (input) => {
         if (input.length === 0) {
+            recordFailure(input, `one of "${chars}"`);
             return failure("unexpected end of input", input);
         }
         const c = input[0];
         if (chars.includes(c)) {
             return char(c)(input);
         }
+        recordFailure(input, `one of "${chars}"`);
         return failure(`expected one of ${escape(chars)}, got ${c}`, input);
     });
 }
@@ -80,9 +83,11 @@ export function oneOf(chars) {
 export function noneOf(chars) {
     return trace(`noneOf(${escape(chars)})`, (input) => {
         if (input.length === 0) {
+            recordFailure(input, `none of "${chars}"`);
             return failure("unexpected end of input", input);
         }
         if (chars.includes(input[0])) {
+            recordFailure(input, `none of "${chars}"`);
             return failure(`expected none of ${escape(chars)}, got ${input[0]}`, input);
         }
         return char(input[0])(input);
@@ -97,26 +102,46 @@ export function noneOf(chars) {
  */
 export const anyChar = trace("anyChar", (input) => {
     if (input.length === 0) {
+        recordFailure(input, "any character");
         return failure("unexpected end of input", input);
     }
     return success(input[0], input.slice(1));
 });
+/**
+ * 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"`.
+ *
+ * @param name - human-readable description of what the parser expects
+ * @param parser - the parser to wrap
+ * @returns - a parser that records the label on failure
+ */
+export function label(name, parser) {
+    return (input) => {
+        const saved = saveRightmostFailure();
+        const result = parser(input);
+        restoreRightmostFailure(saved);
+        if (!result.success)
+            recordFailure(input, name);
+        return result;
+    };
+}
 /** A parser that matches one of " \t\n\r". */
-export const space = oneOf(" \t\n\r");
+export const space = label("whitespace", oneOf(" \t\n\r"));
 /** A parser that matches one or more spaces. */
 export const spaces = many1WithJoin(space);
 /** A parser that matches one digit. */
-export const digit = oneOf("0123456789");
+export const digit = label("a digit", oneOf("0123456789"));
 /** A parser that matches one letter, case insensitive. */
-export const letter = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
+export const letter = label("a letter", oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"));
 /** A parser that matches one digit or letter, case insensitive. */
-export const alphanum = oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
+export const alphanum = label("a letter or digit", oneOf("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"));
 /** A parser that matches one word, case insensitive. */
-export const word = regexParser("^[a-z]+", "ui");
+export const word = label("a word", regexParser("^[a-z]+", "ui"));
 /** A parser that matches one or more digits. */
-export const num = regexParser("^[0-9]+");
+export const num = label("a number", regexParser("^[0-9]+"));
 /** A parser that matches one single or double quote. */
-export const quote = oneOf(`'"`);
+export const quote = label("a quote", oneOf(`'"`));
 /** A parser that matches one tab character. */
 export const tab = char("\t");
 /** A parser that matches one newline ("\n" only) character. */
@@ -126,6 +151,7 @@ export const eof = (input) => {
     if (input === "") {
         return success(null, input);
     }
+    recordFailure(input, "end of input");
     return failure("expected end of input", input);
 };
 /** A parser that matches a quoted string, in single or double quotes.
@@ -154,6 +180,7 @@ export function regexParser(str, options = "") {
         if (match) {
             return success(match[0], input.slice(match[0].length));
         }
+        recordFailure(input, `${str}`);
         return failure(`expected ${str}, got ${input.slice(0, 10)}`, input);
     });
 }
@@ -187,6 +214,7 @@ export function captureRegex(str, options = "", ...captureNames) {
             const captures = Object.assign({}, Object.fromEntries(match.slice(1).map((value, index) => [captureNames[index], value])));
             return success(captures, input.slice(match[0].length));
         }
+        recordFailure(input, `${str}`);
         return failure(`expected ${str}, got ${input.slice(0, 10)}`, input);
     };
     return trace(`captureRegex(${str})`, _parser);

package/dist/position.d.ts

@@ -0,0 +1,45 @@
+import { Parser } from "./types.js";
+export type Position = {
+    offset: number;
+    line: number;
+    column: number;
+};
+export type Span = {
+    start: Position;
+    end: Position;
+};
+/**
+ * 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.
+ */
+export declare function buildLineTable(source: string): number[];
+/**
+ * Convert an absolute offset into a line and column using a precomputed line table.
+ * Both line and column are 0-based.
+ */
+export declare function offsetToPosition(lineTable: number[], offset: number): Position;
+/**
+ * A zero-width parser that returns the current offset into the input string.
+ * Requires `setInputStr` to have been called with the full input.
+ */
+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.
+ */
+export declare const getPosition: Parser<Position>;
+/**
+ * Wraps a parser so that its result includes span information (start and end positions).
+ * Useful for building ASTs with location data for language servers / editors.
+ * Requires `setInputStr` to have been called with the full input.
+ *
+ * @example
+ * ```ts
+ * const locatedWord = withSpan(word);
+ * // Result: { value: "hello", span: { start: { offset: 0, line: 0, column: 0 }, end: { offset: 5, line: 0, column: 5 } } }
+ * ```
+ */
+export declare function withSpan<T>(parser: Parser<T>): Parser<{
+    value: T;
+    span: Span;
+}>;

package/dist/position.js

@@ -0,0 +1,85 @@
+import { getInputStr } from "./trace.js";
+import { success } from "./types.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.
+ */
+export function buildLineTable(source) {
+    const lineStarts = [0];
+    for (let i = 0; i < source.length; i++) {
+        if (source[i] === "\n") {
+            lineStarts.push(i + 1);
+        }
+    }
+    return lineStarts;
+}
+/**
+ * Convert an absolute offset into a line and column using a precomputed line table.
+ * Both line and column are 0-based.
+ */
+export function offsetToPosition(lineTable, offset) {
+    // binary search for the line
+    let lo = 0;
+    let hi = lineTable.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (lineTable[mid] <= offset) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    return {
+        offset,
+        line: lo,
+        column: offset - lineTable[lo],
+    };
+}
+/**
+ * A zero-width parser that returns the current offset into the input string.
+ * Requires `setInputStr` to have been called with the full input.
+ */
+export const getOffset = (input) => {
+    const source = getInputStr();
+    return success(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.
+ */
+export const getPosition = (input) => {
+    const source = getInputStr();
+    const offset = source.length - input.length;
+    const lineTable = buildLineTable(source);
+    return success(offsetToPosition(lineTable, offset), input);
+};
+/**
+ * Wraps a parser so that its result includes span information (start and end positions).
+ * Useful for building ASTs with location data for language servers / editors.
+ * Requires `setInputStr` to have been called with the full input.
+ *
+ * @example
+ * ```ts
+ * const locatedWord = withSpan(word);
+ * // Result: { value: "hello", span: { start: { offset: 0, line: 0, column: 0 }, end: { offset: 5, line: 0, column: 5 } } }
+ * ```
+ */
+export function withSpan(parser) {
+    return (input) => {
+        const source = getInputStr();
+        const lineTable = buildLineTable(source);
+        const startOffset = source.length - input.length;
+        const result = parser(input);
+        if (!result.success)
+            return result;
+        const endOffset = source.length - result.rest.length;
+        return success({
+            value: result.result,
+            span: {
+                start: offsetToPosition(lineTable, startOffset),
+                end: offsetToPosition(lineTable, endOffset),
+            },
+        }, result.rest);
+    };
+}

package/dist/rightmostFailure.d.ts

@@ -0,0 +1,32 @@
+export declare function resetRightmostFailure(): void;
+/**
+ * Record an expected alternative at the current failure position.
+ * If this position is further right than any previous failure, it replaces the previous.
+ * If it's at the same position, it adds to the list of expectations (with dedup).
+ * No-op if `setInputStr` has not been called.
+ *
+ * @param input - the remaining input at the point of failure
+ * @param expected - a human-readable description of what was expected
+ */
+export declare function recordFailure(input: string, expected: string): void;
+/**
+ * Returns the current rightmost failure position and expected alternatives,
+ * or `null` if no failures have been recorded.
+ */
+export declare function getRightmostFailure(): {
+    pos: number;
+    expected: string[];
+} | null;
+type SavedRightmostFailure = {
+    pos: number;
+    expected: string[];
+};
+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.
+ * Returns `null` if no failures have been recorded.
+ * Requires `setInputStr` to have been called.
+ */
+export declare function getErrorMessage(): string | null;
+export {};

package/dist/rightmostFailure.js

@@ -0,0 +1,70 @@
+import { getInputStr } from "./trace.js";
+import { buildLineTable, offsetToPosition } from "./position.js";
+let rightmostFailurePos = -1;
+let rightmostFailureExpected = [];
+export function resetRightmostFailure() {
+    rightmostFailurePos = -1;
+    rightmostFailureExpected = [];
+}
+/**
+ * Record an expected alternative at the current failure position.
+ * If this position is further right than any previous failure, it replaces the previous.
+ * If it's at the same position, it adds to the list of expectations (with dedup).
+ * No-op if `setInputStr` has not been called.
+ *
+ * @param input - the remaining input at the point of failure
+ * @param expected - a human-readable description of what was expected
+ */
+export function recordFailure(input, expected) {
+    const source = getInputStr();
+    if (source.length === 0)
+        return;
+    const pos = source.length - input.length;
+    if (pos > rightmostFailurePos) {
+        rightmostFailurePos = pos;
+        rightmostFailureExpected = [expected];
+    }
+    else if (pos === rightmostFailurePos) {
+        if (!rightmostFailureExpected.includes(expected)) {
+            rightmostFailureExpected.push(expected);
+        }
+    }
+}
+/**
+ * Returns the current rightmost failure position and expected alternatives,
+ * or `null` if no failures have been recorded.
+ */
+export function getRightmostFailure() {
+    if (rightmostFailurePos < 0)
+        return null;
+    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+}
+export function saveRightmostFailure() {
+    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+}
+export function restoreRightmostFailure(saved) {
+    rightmostFailurePos = saved.pos;
+    rightmostFailureExpected = [...saved.expected];
+}
+function formatExpected(expected) {
+    if (expected.length === 1)
+        return expected[0];
+    if (expected.length === 2)
+        return `${expected[0]} or ${expected[1]}`;
+    return expected.slice(0, -1).join(", ") + ", or " + expected[expected.length - 1];
+}
+/**
+ * Formats the rightmost failure into a human-readable error message with line and column info.
+ * Returns `null` if no failures have been recorded.
+ * Requires `setInputStr` to have been called.
+ */
+export function getErrorMessage() {
+    if (rightmostFailurePos < 0)
+        return null;
+    const source = getInputStr();
+    const lineTable = buildLineTable(source);
+    const pos = offsetToPosition(lineTable, rightmostFailurePos);
+    const line = pos.line + 1;
+    const column = pos.column + 1;
+    return `Line ${line}, col ${column}: expected ${formatExpected(rightmostFailureExpected)}`;
+}

package/dist/tarsecError.d.ts

@@ -1,4 +1,4 @@
-type TarsecErrorData = {
+export type TarsecErrorData = {
     line: number;
     column: number;
     length: number;
@@ -9,4 +9,3 @@ export declare class TarsecError extends Error {
     data: TarsecErrorData;
     constructor(error: TarsecErrorData);
 }
-export {};

package/dist/trace.d.ts

@@ -1,4 +1,5 @@
-import { ParserResult, Parser, PlainObject, CaptureParser } from "./types.js";
+import { ParserResult, Parser, PlainObject, CaptureParser, ParserFailure } from "./types.js";
+import { TarsecErrorData } from "./tarsecError.js";
 export declare function setTraceHost(host: string): void;
 export declare function getTraceHost(): string;
 export declare function setTraceId(id: string): void;
@@ -122,3 +123,4 @@ export declare function limitSteps(limit: number, callback: Function): void;
  */
 export declare function setInputStr(s: string): void;
 export declare function getInputStr(): string;
+export declare function getDiagnostics(result: ParserFailure, input: string, _message?: string): TarsecErrorData;

package/dist/trace.js

@@ -1,6 +1,7 @@
 import { escape, round, shorten } from "./utils.js";
 import process from "process";
 import { execSync } from "child_process";
+import { resetRightmostFailure } from "./rightmostFailure.js";
 const isNode = typeof process !== "undefined" &&
     process.versions != null &&
     process.versions.node != null;
@@ -194,7 +195,50 @@ let inputStr = "";
  */
 export function setInputStr(s) {
     inputStr = s;
+    resetRightmostFailure();
 }
 export function getInputStr() {
     return inputStr;
 }
+export function getDiagnostics(result, input, _message) {
+    const inputStr = getInputStr();
+    const messages = [];
+    const prefix = "Near: ";
+    const message = _message || result.message || "Parsing failed";
+    if (inputStr.length > 0) {
+        const index = inputStr.length - input.length;
+        const start = Math.max(0, index - 20);
+        const end = Math.min(inputStr.length, index + 20);
+        const previewStr = inputStr.substring(start, end).split("\n")[0];
+        messages.push(`${prefix}${previewStr}`);
+        messages.push(`${" ".repeat(index + prefix.length)}^`);
+        messages.push(message);
+        const lines = inputStr.split("\n");
+        let acc = 0;
+        let i = 0;
+        while (index >= acc && i < lines.length) {
+            acc += lines[i].length;
+            i++;
+        }
+        const linesIndex = Math.max(0, i - 1);
+        const column = lines[linesIndex].length - (acc - index);
+        return {
+            line: i - 1,
+            column,
+            length: 1,
+            prettyMessage: messages.join("\n"),
+            message: message,
+        };
+    }
+    else {
+        messages.push(`${prefix}${input.substring(1, 100)}`);
+        messages.push(message);
+        return {
+            line: 0,
+            column: 0,
+            length: 0,
+            prettyMessage: messages.join("\n"),
+            message: message,
+        };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -38,4 +38,4 @@
     "typescript": "^5.4.2",
     "vitest": "^1.4.0"
   }
-}
+}