tarsec 0.4.7 → 0.5.1

package/README.md

@@ -36,6 +36,7 @@ parser("hello there"); // failure
 ## Learning tarsec
 - [A five minute introduction](/tutorials/5-minute-intro.md)
 - [The three building blocks in tarsec](/tutorials/three-building-blocks.md)
+- [Lexemes: your grammar's token vocabulary](/tutorials/lexemes.md)
 - [API reference](https://egonschiele.github.io/tarsec/)
 
 ## Features

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

@@ -5,3 +5,6 @@ export * from "./types.js";
 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

@@ -5,3 +5,6 @@ export * from "./types.js";
 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/lexeme.d.ts

@@ -0,0 +1,71 @@
+import { CharPredicate } from "./parsers.js";
+import { CaptureParser, Parser, PlainObject } from "./types.js";
+/** Configuration for `makeLexemes`. */
+export type LexemeConfig = {
+    /** Characters eaten after every lexeme, e.g. " \t". */
+    whitespace: string;
+    /** Line-comment marker (e.g. "#" or "//"); comments are eaten as whitespace,
+     * up to but NOT including the newline (newlines may be significant). */
+    lineComment?: string;
+    /** When true, `\` followed by a newline is also eaten as whitespace. */
+    lineContinuation?: boolean;
+    /** Charset or predicate for an identifier's first character.
+     * Defaults to letters and "_". */
+    identStart?: string | CharPredicate;
+    /** Charset or predicate for subsequent identifier characters.
+     * Defaults to letters, digits, and "_". */
+    identRest?: string | CharPredicate;
+    /** Words `identifier` refuses to match (and `keyword` accepts). */
+    keywords?: string[];
+    /** Charset or predicate for characters that can appear in operators.
+     * `operator` uses it for longest-match rejection: `operator("<")` refuses
+     * to match the front of `<=`. Defaults to common symbol characters. */
+    operatorChars?: string | CharPredicate;
+};
+export type Lexemes = {
+    /** Whitespace/comment skipper as a parser. Always succeeds. Use once at the
+     * top of a grammar to eat leading whitespace; lexemes handle the rest. */
+    whitespace: Parser<null>;
+    /** Whitespace/comment skipper as a total function: returns the input with
+     * leading whitespace removed. Handy where a parser result would force
+     * callers to handle a failure that cannot happen. */
+    skipWhitespace: (input: string) => string;
+    /** Run a parser, then eat trailing whitespace/comments. Capture-preserving. */
+    lexeme: {
+        <T, C extends PlainObject>(parser: CaptureParser<T, C>): CaptureParser<T, C>;
+        <T>(parser: Parser<T>): Parser<T>;
+    };
+    /** `lexeme(str(s))` — match a literal, eat trailing whitespace. */
+    symbol: <const S extends string>(s: S) => Parser<S>;
+    /** Match an identifier (per identStart/identRest), rejecting keywords. */
+    identifier: Parser<string>;
+    /** Match `s` only when not followed by an identRest character, so
+     * `keyword("if")` rejects "ifx". */
+    keyword: (s: string) => Parser<string>;
+    /** Match `s` only when not followed by an operator character, so
+     * `operator("<")` rejects the front of "<=". The symbolic counterpart
+     * of `keyword`. */
+    operator: (s: string) => Parser<string>;
+    /** Run a parser between "(" and ")", whitespace handled. Returns the
+     * inner result. */
+    parens: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "[" and "]". */
+    brackets: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "{" and "}". */
+    braces: <T>(parser: Parser<T>) => Parser<T>;
+    /** Zero or more of `parser`, separated by commas. */
+    commaSep: <T>(parser: Parser<T>) => Parser<T[]>;
+    /** One or more of `parser`, separated by commas. */
+    commaSep1: <T>(parser: Parser<T>) => Parser<T[]>;
+};
+/**
+ * Build a set of lexeme helpers: ordinary parsers that handle whitespace,
+ * comments, and keywords in one place. This is a *scannerless* lexeme layer
+ * (like Parsec's `makeTokenParser`), not a lexer — there is no separate pass
+ * and no token array.
+ *
+ * The discipline: every token-shaped parser eats its own *trailing*
+ * whitespace; eat *leading* whitespace once at the top with `whitespace`
+ * (or `skipWhitespace`).
+ */
+export declare function makeLexemes(config: LexemeConfig): Lexemes;