parseman 0.12.0 → 0.14.0

package/dist/functional/run.d.ts

@@ -0,0 +1,63 @@
+import type { Combinator, ParseContext, ParseError, ParseResult } from '../types.ts';
+/**
+ * Run a compiled/interpreted grammar entry against an input and collect the raw
+ * outcome a tool needs to shape a parse result — WITHOUT the consumer having to
+ * hand-build a `ctx`, branch on function-vs-combinator, or scan for leftover
+ * input itself.
+ *
+ * A `compile()`/macro grammar hands you a map of bare parse FUNCTIONS; the
+ * interpreter hands you COMBINATORS. `run()` invokes either, threads the standard
+ * framework ctx (trivia log, recover/expect error sink, the `ctx.build` host,
+ * grammar state), and — given the grammar's trivia parser — reports where
+ * non-trivia input was left unconsumed. The consumer keeps only its own policy:
+ * how to shape the tree and how to turn diagnostics into its error type.
+ */
+/** A compiled rule (macro/`compile()` output) OR an interpreter combinator. */
+export type Runnable = ((input: string, pos: number, ctx: ParseContext) => ParseResult<unknown>) | Combinator<unknown>;
+export type RunOptions = {
+    /** `ctx.build` host — makes structural `node()` rules build a CST / AST via the
+     * host instead of their own eval builders. Omit for a grammar's own builders. */
+    build?: ParseContext['build'];
+    /** Initial grammar state threaded into `ctx.state`. */
+    state?: unknown;
+    /**
+     * The grammar's trivia rule. A root rule consumes trivia BETWEEN terms but not
+     * after the last one, so trailing whitespace/comments would otherwise look like
+     * unparsed input. Given the trivia rule, `run` skips that tail before computing
+     * `unconsumedFrom` — so only real leftover is reported. Also encodes dialect
+     * differences for free: pass the CSS trivia and a trailing `//` counts as
+     * leftover; pass the Less trivia (which treats `//` as a line comment) and it
+     * doesn't. An UNTERMINATED comment (which the trivia rule won't match) surfaces
+     * at its start. Omit to require the parse to reach the exact end itself.
+     */
+    trivia?: Runnable;
+};
+export type RunResult = {
+    ok: boolean;
+    /** The entry's value on success; undefined on failure. */
+    value: unknown;
+    span: {
+        start: number;
+        end: number;
+    };
+    /** Expected-token set when the TOP-LEVEL parse failed (empty on success). */
+    expected: string[];
+    /** `recover()` / `expect()` diagnostics collected during the parse (in order). */
+    errors: ParseError[];
+    /**
+     * Flat trivia log for building a trivia map. Entry width depends on whether the
+     * grammar uses labeled trivia: 2 numbers per entry (`start, end`) for plain
+     * trivia, 3 numbers per entry (`start, end, kindIndex`) for labeled trivia
+     * (grammars with `label()` arms in their trivia choice). Use `buildTriviaIndex`
+     * / `triviaEntries` to consume it format-agnostically rather than iterating raw.
+     */
+    triviaLog: number[];
+    /** Offset where unparsed input begins — the first non-trivia character the parse
+     * left unconsumed (trailing trivia skipped when `trivia` is given), or null if
+     * the whole input was consumed. This is how you detect "the grammar stopped short,
+     * there's junk here". Only meaningful on success — a failed parse reports its own
+     * `span`/`expected`. */
+    unconsumedFrom: number | null;
+};
+export declare function run(entry: Runnable, input: string, options?: RunOptions): RunResult;
+//# sourceMappingURL=run.d.ts.map

package/dist/functional/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/functional/run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpF;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,QAAQ,GAChB,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,KAAK,WAAW,CAAC,OAAO,CAAC,CAAC,GACzE,UAAU,CAAC,OAAO,CAAC,CAAA;AAEvB,MAAM,MAAM,UAAU,GAAG;IACvB;qFACiF;IACjF,KAAK,CAAC,EAAE,YAAY,CAAC,OAAO,CAAC,CAAA;IAC7B,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,OAAO,CAAA;IACX,0DAA0D;IAC1D,KAAK,EAAE,OAAO,CAAA;IACd,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAA;IACpC,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,kFAAkF;IAClF,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB;;;;4BAIwB;IACxB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAKD,wBAAgB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,UAAe,GAAG,SAAS,CAgCvF"}