@tabnas/parser 0.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2013-2026 Richard Rodger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# tabnas
+
+A pluggable parsing engine. The runtime is a class — `Tabnas` — that
+runs a rule-based parser over a configurable matcher-based lexer. The
+package ships **no grammar** of its own: every grammar is a plugin
+that you (or another package) supply.
+
+```bash
+npm install @tabnas/parser
+```
+
+A tiny taste — a one-token grammar defined inline:
+
+```js
+const { Tabnas } = require('@tabnas/parser')
+
+const tn = new Tabnas({ plugins: [(tn) => {
+  tn.options({ fixed: { token: { '#HI': 'hello' } } })
+  tn.rule('val', (rs) => rs.open([
+    { s: ['#HI'], a: (r) => { r.node = 'world' } },
+  ]))
+}] })
+
+tn.parse('hello')                     // 'world'
+```
+
+That grammar as a railroad/syntax diagram, generated from the live parser
+with [`@tabnas/railroad`](https://github.com/tabnas/railroad):
+
+![tabnas taste-grammar railroad diagram](doc/taste.svg)
+
+A vertical ASCII version is in [`doc/taste.txt`](doc/taste.txt).
+
+## Documentation
+
+- [Tutorial](doc/tutorial.md) — build your first parser, step by step.
+- [How-to guides](doc/guide.md) — short recipes for common tasks.
+- [Writing plugins](doc/plugins.md) — author a grammar or tooling
+  plugin.
+- [API reference](doc/api.md) — every public method, property, and
+  export.
+- [Options reference](doc/options.md) — every option field and its
+  default.
+- [Concepts](doc/concepts.md) — how the TypeScript engine is put
+  together, and why.
+
+Shared design docs for both runtimes live at the top of the repo:
+
+- [Architecture](../doc/architecture.md) — the engine model.
+- [Syntax](../doc/syntax.md) — the relaxed-JSON syntax reference.
+
+### Explanation / design notes
+
+- [BNF feasibility](doc/bnf-to-tabnas-feasibility.md) — turning
+  BNF / ABNF into engine rules.
+- [LSP feasibility](doc/lsp-feasibility.md) — language-server angles.
+
+## Companion packages
+
+Grammars and tooling ship as separate packages, not in this one:
+
+- `@tabnas/abnf` — compiles ABNF into engine rules and adds
+  `tn.bnf(src)`.
+- `@tabnas/debug` — tracing and `describe()` helpers.
+
+The strict-JSON grammar used by the conformance tests lives as a test
+fixture at [`test/json-plugin.ts`](test/json-plugin.ts) — a worked
+example of a non-trivial grammar plugin.
+
+The [Go port](../go/) follows the same grammar-free design, with its
+strict-JSON grammar kept as a test fixture too.
+
+## License
+
+MIT. Copyright (c) Richard Rodger.

package/dist/builtins.d.ts

@@ -0,0 +1,4 @@
+import type { AltAction, AltCond } from './types';
+export declare const BUILTIN_SCHEMA_VERSION = 2;
+export type BuiltinRef = AltAction | AltCond;
+export declare const BUILTIN_REFS: Readonly<Record<string, BuiltinRef>>;

package/dist/builtins.js

@@ -0,0 +1,202 @@
+"use strict";
+/* Copyright (c) 2026 Richard Rodger and other contributors, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_REFS = exports.BUILTIN_SCHEMA_VERSION = void 0;
+// The config-schema version implemented by these builtins. A serialized
+// grammar that declares `GrammarSpec.v` greater than this is refused at
+// load (see Tabnas.grammar). Absent ⇒ treated as version 1.
+exports.BUILTIN_SCHEMA_VERSION = 2;
+const defprop = Object.defineProperty;
+// Attach the engine's info marker as a hidden (non-enumerable) property on
+// a node, so a grammar running with `info` on can introspect a container's
+// origin (implicit flag, meta bag) or a string's quote without the marker
+// leaking into JSON output. The TS info carrier (the marker property) is
+// the counterpart of Go's MapRef/ListRef/Text wrapper structs.
+function markNode(node, marker, data) {
+    if (node != null && 'object' === typeof node) {
+        defprop(node, marker, { value: data, writable: true });
+    }
+}
+function mkNode(rule, kind) {
+    return 'user' === kind ? { rule, src: '', kids: [] } : { src: '', kids: [] };
+}
+// ---- Tree builders (config in `alt.k.<name>`) ---------------------
+// These mirror @tabnas/abnf's emitter closures so a serialized,
+// function-free grammar builds the identical `{rule,src,kids}` tree.
+// Allocate (when `init`) and/or accumulate matched terminals' src.
+const node$ = (r, _ctx, alt) => {
+    const cfg = (alt && alt.k && alt.k.node$) || {};
+    if (cfg.init)
+        r.node = mkNode(cfg.rule, cfg.kind);
+    const n = r.node;
+    const nterms = cfg.nterms || 0;
+    for (let i = 0; i < nterms; i++)
+        n.src += r.o[i].src;
+};
+// Merge the just-returned child node into the current node. Tagged
+// children push into `kids`; untagged ones flatten (src concatenates,
+// kids extend).
+const capture$ = (r, _ctx, alt) => {
+    const cfg = (alt && alt.k && alt.k.capture$) || {};
+    if (null == r.node)
+        r.node = mkNode(cfg.rule, cfg.kind);
+    const n = r.node;
+    const c = r.child && r.child.node;
+    if (null == c)
+        return;
+    if ('object' !== typeof c || !('src' in c)) {
+        n.kids.push(c);
+        return;
+    }
+    if (c === n)
+        return;
+    n.src += c.src;
+    if (c.rule)
+        n.kids.push(c);
+    else if (Array.isArray(c.kids))
+        n.kids.push(...c.kids);
+};
+// Lift the committed child's node straight up (no merge).
+const bubble$ = (r) => {
+    if (r.child && r.child.node !== undefined)
+        r.node = r.child.node;
+};
+// ---- Probe + phase-retry dispatch ---------------------------------
+// Phase-0 open action: mark the token position and reset phase.
+const probeInit$ = (r, ctx) => {
+    r.k.pd_phase = 0;
+    r.k.pd_mark = ctx.mark();
+};
+// Phase-0 close action: peek the first token the probe did not consume,
+// rewind to the mark, and commit to phase 1 (disambiguator present) or
+// phase 2 (absent). The probe never fails, so `ctx.t[0]` always reflects
+// a real position (the compiler emits a phase-0 close that consumes
+// nothing — that contract is required for this builtin to be correct).
+const probeDecide$ = (r, ctx) => {
+    // The phase-0 close must follow a phase-0 open (`@probeInit$`), which
+    // records `pd_mark`. Guard against a malformed grammar that runs the
+    // decision without it: `ctx.rewind(undefined)` would silently corrupt
+    // the rewind window (NaN), breaking every later mark/rewind.
+    if (null == r.k.pd_mark) {
+        throw new Error('@probeDecide$: no pd_mark — phase-0 @probeInit$ did not run');
+    }
+    const peek = ctx.t[0];
+    ctx.rewind(r.k.pd_mark);
+    r.k.pd_phase = peek && peek.name === r.k.pd_d ? 1 : 2;
+};
+// Phase-guard conditions.
+const probePhase0$ = (r) => !r.k.pd_phase;
+const probePhase1$ = (r) => 1 === r.k.pd_phase;
+const probePhase2$ = (r) => 2 === r.k.pd_phase;
+// ---- Native-value builders (config in `alt.k.<name>`) -------------
+// Build NATIVE JSON values (objects/arrays/scalars), as opposed to the
+// `{rule,src,kids}` syntax tree of the tree builders above. A grammar
+// whose rules thread a node from parent to child (the engine seeds a
+// pushed child's node from the parent — see makeRule) can assemble plain
+// objects/arrays with these as alt actions. Schema family v2.
+//
+// These are INFO-AWARE: with `cfg.info` off they emit PLAIN nodes
+// (byte-identical to v1); with `cfg.info.{map,list,text}` on they attach
+// the engine's introspection marker (origin/quote metadata) — the same
+// info model the Go engine carries via MapRef/ListRef/Text. The info
+// logic lives here, in the engine, instead of each JSON-family plugin
+// re-hand-writing it. See doc/value-builtins.md.
+// Allocate a fresh empty object into r.node (no prototype, like JSON).
+// When info.map is on, attach the marker with the static `implicit` flag.
+const object$ = (r, ctx, alt) => {
+    const node = Object.create(null);
+    r.node = node;
+    if (ctx.cfg.info.map) {
+        const cfg = (alt && alt.k && alt.k.object$) || {};
+        markNode(node, ctx.cfg.info.marker, { implicit: !!cfg.implicit, meta: {} });
+    }
+};
+// Allocate a fresh empty array into r.node. When info.list is on, attach
+// the marker with the static `implicit` flag.
+const array$ = (r, ctx, alt) => {
+    const node = [];
+    r.node = node;
+    if (ctx.cfg.info.list) {
+        const cfg = (alt && alt.k && alt.k.array$) || {};
+        markNode(node, ctx.cfg.info.marker, { implicit: !!cfg.implicit, meta: {} });
+    }
+};
+// Clear r.node back to "no value" — undoes the parent-seeded node so a
+// scalar value (or fresh container) doesn't inherit the parent container.
+const reset$ = (r) => {
+    r.node = undefined;
+};
+// Capture the matched key token's value into a (non-propagated) r.u slot,
+// for a later @setval$ on the same rule to consume.
+const key$ = (r, _ctx, alt) => {
+    const cfg = (alt && alt.k && alt.k.key$) || {};
+    r.u[cfg.slot || 'key'] = r.o[cfg.from || 0]?.val;
+};
+// Assign the just-returned child node under the captured key: the object-
+// property set. No-op if r.node isn't an object. When info.map is on, a
+// key that collides with the marker is dropped (the marker rides as a
+// hidden property, so a literal `"__info__"` key must not overwrite it) —
+// this guard is TS-only; Go's field-based metadata has no key collision.
+const setval$ = (r, ctx, alt) => {
+    const cfg = (alt && alt.k && alt.k.setval$) || {};
+    const n = r.node;
+    if (null != n && 'object' === typeof n) {
+        const key = r.u[cfg.slot || 'key'];
+        if (ctx.cfg.info.map && key === ctx.cfg.info.marker)
+            return;
+        n[key] = r.child.node;
+    }
+};
+// Append the just-returned child node to the array (skips the no-value
+// child). No-op if r.node isn't an array.
+const push$ = (r) => {
+    if (undefined !== r.child.node && Array.isArray(r.node)) {
+        r.node.push(r.child.node);
+    }
+};
+// Coalesce a value: a built child node wins; otherwise resolve the
+// matched scalar token. When info.text is on and the resolved scalar is a
+// string from a string/text token, box it as a `String` carrying the
+// quote char (the leaf whose output type changes under info — it has no
+// container to hang the marker on). The Go counterpart wraps in a `Text`.
+const value$ = (r, ctx, alt) => {
+    if (undefined !== r.child.node) {
+        r.node = r.child.node;
+        return;
+    }
+    const cfg = (alt && alt.k && alt.k.value$) || {};
+    const tok = r.o[cfg.from || 0];
+    let val = tok ? tok.resolveVal(r, ctx) : undefined;
+    const info = ctx.cfg.info;
+    if (info.text &&
+        'string' === typeof val &&
+        tok &&
+        (tok.tin === ctx.cfg.t.ST || tok.tin === ctx.cfg.t.TX)) {
+        const quote = tok.tin === ctx.cfg.t.ST && tok.src.length > 0 ? tok.src[0] : '';
+        const sv = new String(val);
+        markNode(sv, info.marker, { quote });
+        val = sv;
+    }
+    r.node = val;
+};
+// The standard builtin library, frozen so a grammar that (illegally)
+// overrides a `$` ref cannot mutate the shared map for other instances.
+exports.BUILTIN_REFS = Object.freeze({
+    '@node$': node$,
+    '@capture$': capture$,
+    '@bubble$': bubble$,
+    '@probeInit$': probeInit$,
+    '@probeDecide$': probeDecide$,
+    '@probePhase0$': probePhase0$,
+    '@probePhase1$': probePhase1$,
+    '@probePhase2$': probePhase2$,
+    // Native-value builders (schema v2).
+    '@object$': object$,
+    '@array$': array$,
+    '@reset$': reset$,
+    '@key$': key$,
+    '@setval$': setval$,
+    '@push$': push$,
+    '@value$': value$,
+});
+//# sourceMappingURL=builtins.js.map

package/dist/builtins.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.js","sourceRoot":"","sources":["../src/builtins.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -0,0 +1,64 @@
+import type { Tabnas, Config, LexSub, TabnasOptions, Plugin, Rule, RuleSpec, RuleSub, Tin, Token } from './types';
+export type ContextInit = {
+    opts: TabnasOptions;
+    cfg: Config;
+    meta: Record<string, any>;
+    src: () => string;
+    root: () => any;
+    plgn: () => Plugin[];
+    inst: () => Tabnas;
+    sub: {
+        lex?: LexSub[];
+        rule?: RuleSub[];
+    };
+    rsm: {
+        [name: string]: RuleSpec;
+    };
+    F: (s: any) => string;
+    NOTOKEN: Token;
+    NORULE: Rule;
+};
+export declare class Context {
+    [key: string]: any;
+    uI: number;
+    opts: TabnasOptions;
+    cfg: Config;
+    meta: Record<string, any>;
+    src: () => string;
+    root: () => any;
+    plgn: () => Plugin[];
+    inst: () => Tabnas;
+    rule: Rule;
+    sub: {
+        lex?: LexSub[];
+        rule?: RuleSub[];
+    };
+    xs: Tin;
+    v: Token[];
+    vAbs: number;
+    t: Token[];
+    tC: number;
+    kI: number;
+    rs: Rule[];
+    rsI: number;
+    rsm: {
+        [name: string]: RuleSpec;
+    };
+    log?: (...rest: any) => void;
+    F: (s: any) => string;
+    u: Record<string, any>;
+    NOTOKEN: Token;
+    NORULE: Rule;
+    lex?: any;
+    constructor(init: ContextInit);
+    get t0(): Token;
+    set t0(tkn: Token);
+    get t1(): Token;
+    set t1(tkn: Token);
+    get v1(): Token;
+    set v1(tkn: Token);
+    get v2(): Token;
+    set v2(tkn: Token);
+    mark(): number;
+    rewind(mark: number): void;
+}

package/dist/context.js

@@ -0,0 +1,138 @@
+"use strict";
+/* Copyright (c) 2013-2026 Richard Rodger, MIT License */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+// Per-parse state object passed to every rule action and lex matcher.
+class Context {
+    constructor(init) {
+        this.uI = 0; // Rule index.
+        this.xs = -1; // Lex state tin.
+        // Consumed-token history; v1 / v2 (below) read from the top of this stack.
+        this.v = [];
+        // Absolute count of pushed-not-rewound tokens since parse start; mark()
+        // returns it so ring-buffer eviction of old entries doesn't invalidate marks.
+        this.vAbs = 0;
+        this.tC = -2; // Prepare count for lookahead (two seeded slots).
+        this.kI = -1; // Parser rule iteration count.
+        this.rs = []; // Rule stack.
+        this.rsI = 0; // Rule stack index.
+        this.u = {}; // Custom meta data (for use by plugins).
+        this.opts = init.opts;
+        this.cfg = init.cfg;
+        this.meta = init.meta;
+        this.src = init.src;
+        this.root = init.root;
+        this.plgn = init.plgn;
+        this.inst = init.inst;
+        this.sub = init.sub;
+        this.rsm = init.rsm;
+        this.F = init.F;
+        this.NOTOKEN = init.NOTOKEN;
+        this.NORULE = init.NORULE;
+        this.rule = init.NORULE; // overwritten by parser.start once the
+        // root rule is built; safe placeholder.
+        this.t = [init.NOTOKEN, init.NOTOKEN];
+    }
+    // Legacy aliases for the first two slots of the lookahead buffer.
+    // Reading an unfetched slot yields NOTOKEN; writing seeds the slot.
+    // @deprecated Use t[0] / t[1] directly in new grammar code.
+    get t0() {
+        return this.t[0] ?? this.NOTOKEN;
+    }
+    set t0(tkn) {
+        this.t[0] = tkn;
+    }
+    get t1() {
+        return this.t[1] ?? this.NOTOKEN;
+    }
+    set t1(tkn) {
+        this.t[1] = tkn;
+    }
+    // Most-recently-consumed token (top of the v stack).
+    // Setting v1 with an empty stack pushes; otherwise replaces top.
+    get v1() {
+        return this.v[this.v.length - 1] ?? this.NOTOKEN;
+    }
+    set v1(tkn) {
+        if (0 < this.v.length)
+            this.v[this.v.length - 1] = tkn;
+        else
+            this.v.push(tkn);
+    }
+    // Token before the previous one (one below the top).
+    get v2() {
+        return this.v[this.v.length - 2] ?? this.NOTOKEN;
+    }
+    set v2(tkn) {
+        const L = this.v.length;
+        if (1 < L)
+            this.v[L - 2] = tkn;
+        else if (1 === L)
+            this.v.unshift(tkn);
+        else
+            this.v.push(tkn);
+    }
+    // Save a rewind mark at the current parse position. The returned
+    // value can be passed to rewind() to replay the tokens consumed
+    // since the mark was taken, re-feeding them through the lexer's
+    // pending-token queue.
+    mark() {
+        return this.vAbs;
+    }
+    // Replay the tokens consumed since the given mark.
+    //
+    // Marks are absolute rather than array-relative so the ring-buffer
+    // cap (options.rewind.history) can evict old tokens from the front
+    // of v without invalidating mark values held by in-flight rule
+    // actions. A rewind whose target has been evicted throws — the
+    // caller's retained-history budget was too small for the grammar.
+    rewind(mark) {
+        const k = this.vAbs - mark;
+        if (k <= 0)
+            return;
+        if (k > this.v.length) {
+            throw new Error(`tabnas: ctx.rewind target ${mark} is outside the retained ` +
+                `history window (oldest mark available is ${this.vAbs - this.v.length}, ` +
+                `current is ${this.vAbs}); increase options.rewind.history.`);
+        }
+        const queue = this.lex.pnt.token;
+        const NOTOKEN = this.NOTOKEN;
+        // The lookahead buffer (this.t) holds tokens the lexer has already
+        // produced past the current consumed position but that haven't
+        // been committed to this.v yet. They advanced the lexer's sI — so
+        // if we just invalidated the buffer, those source chars would be
+        // lost. Preserve them by splicing into the front of the pending
+        // queue in the order the lexer produced them, BEHIND the rewound
+        // consumed tokens that come next.
+        const pendingLookahead = [];
+        for (let i = 0; i < this.t.length; i++) {
+            const tkn = this.t[i];
+            if (tkn && tkn !== NOTOKEN)
+                pendingLookahead.push(tkn);
+            this.t[i] = NOTOKEN;
+        }
+        // Un-shift pre-lexed lookahead (oldest-first order at the queue
+        // head), so the next lex.next() serves them in the same order
+        // they were originally produced.
+        for (let i = pendingLookahead.length - 1; i >= 0; i--) {
+            queue.unshift(pendingLookahead[i]);
+        }
+        // Then unshift the rewound consumed tokens — they go in FRONT of
+        // the lookahead, so the next lex.next() serves the oldest rewound
+        // consumed token first, then the rest in order.
+        for (let i = 0; i < k; i++) {
+            // Pop newest-first, unshift in that order — the first unshift
+            // lands the newest at the queue's head; the next unshift slides
+            // older tokens in front of it, so the queue reads oldest-first.
+            queue.unshift(this.v.pop());
+        }
+        this.vAbs -= k;
+        // Clear the lexer's cached end-of-source token so lex.next serves
+        // from the newly-replenished queue rather than short-circuiting
+        // to #ZZ. (Once the lexer has produced the end token it pins it
+        // to pnt.end; the rewound tokens would otherwise be unreachable.)
+        this.lex.pnt.end = undefined;
+    }
+}
+exports.Context = Context;
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/defaults.d.ts

@@ -0,0 +1,3 @@
+import { TabnasOptions } from './tabnas';
+declare const defaults: TabnasOptions;
+export { defaults };