grammatik 0.1.0

package/src/runtime.js

@@ -0,0 +1,16 @@
+// @ts-check
+'use strict'
+
+/**
+ * The surface a generated parser module needs at run time.
+ *
+ * `emitModule` writes files that import from `grammatik/runtime` rather than
+ * from the main entry point, so a generated parser pulls in the lexer, the parse
+ * state and error construction — but not the analyzer, the planner, or the code
+ * generator, none of which it can ever use. The grammar was already analyzed
+ * when the file was written.
+ */
+
+export { FAIL, expect, createState, buildParseError, ParseError } from './state.js'
+export { createLexer, LexError } from './lexer.js'
+export { createValueMethods } from './values.js'

package/src/state.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Records that `expectation` would have been accepted at the cursor, keeping
+ * only the *furthest* position — the alternative that got deepest is almost
+ * always the one the author meant.
+ *
+ * Tracking is off during the first parse. `expect` fires on every failed token
+ * match, so the bookkeeping (acceptable tokens, rule stack) is most of the work
+ * in a backtracking grammar — slicing the rule stack per advance measured ~50x.
+ * On failure `parseTokens` re-runs with `track` on and builds the message from
+ * that; the parser is deterministic, so it lands in the same place.
+ *
+ * @param {ParserState} state
+ * @param {string} expectation
+ */
+export function expect(state: ParserState, expectation: string): void;
+/**
+ * @param {ParserState} state
+ * @returns {ParseError}
+ */
+export function buildParseError(state: ParserState): ParseError;
+/**
+ * The sentinel returned by any parser that did not match. A symbol, so a rule
+ * stays free to legitimately produce `null`/`undefined`, and nothing in JSON
+ * Logic can forge it.
+ */
+export const FAIL: unique symbol;
+export function createState(tokens: import("./lexer.js").Token[], grammar: Record<string, any>, options?: {
+    memo?: boolean;
+    maxSteps?: number;
+    track?: boolean;
+}): ParserState;
+export class ParseError extends Error {
+    /**
+     * @param {string} message
+     * @param {{ token: import('./lexer.js').Token | null, expected: string[], ruleStack: string[] }} details
+     */
+    constructor(message: string, details: {
+        token: import("./lexer.js").Token | null;
+        expected: string[];
+        ruleStack: string[];
+    });
+    token: import("./lexer.js").Token;
+    expected: string[];
+    ruleStack: string[];
+}
+/**
+ * One mutable object threaded through the whole parse as the JSON Logic
+ * *context*. Mutation rather than a rebuilt state per step is what keeps this
+ * fast: `{"val": "idx"}` reads the cursor with no allocation, and backtracking
+ * is a single integer assignment.
+ */
+export type ParserState = {
+    tokens: import("./lexer.js").Token[];
+    /**
+     * Cursor into `tokens`.
+     */
+    idx: number;
+    /**
+     * Furthest cursor reached, for error reporting.
+     */
+    maxIdx: number;
+    /**
+     * Token types acceptable at `maxIdx`.
+     */
+    expected: string[];
+    /**
+     * Rule name -> JSON Logic.
+     */
+    grammar: Record<string, any>;
+    /**
+     * Packrat cache, when enabled.
+     */
+    memo: Map<string, any> | null;
+    /**
+     * Rule-name stack, written by index, never popped.
+     */
+    ruleNames: string[];
+    /**
+     * Live depth within `ruleNames`.
+     */
+    ruleDepth: number;
+    /**
+     * Snapshot taken at the furthest failure.
+     */
+    failureStack: string[] | null;
+    /**
+     * Whether to record error-reporting detail.
+     */
+    track: boolean;
+    /**
+     * Combinator invocations, for the runaway guard.
+     */
+    steps: number;
+    /**
+     * 0 disables the guard.
+     */
+    maxSteps: number;
+};

package/src/state.js

@@ -0,0 +1,121 @@
+// @ts-check
+'use strict'
+
+/**
+ * The sentinel returned by any parser that did not match. A symbol, so a rule
+ * stays free to legitimately produce `null`/`undefined`, and nothing in JSON
+ * Logic can forge it.
+ */
+export const FAIL = Symbol('grammatik.fail')
+
+/**
+ * One mutable object threaded through the whole parse as the JSON Logic
+ * *context*. Mutation rather than a rebuilt state per step is what keeps this
+ * fast: `{"val": "idx"}` reads the cursor with no allocation, and backtracking
+ * is a single integer assignment.
+ *
+ * @typedef {object} ParserState
+ * @property {import('./lexer.js').Token[]} tokens
+ * @property {number} idx           Cursor into `tokens`.
+ * @property {number} maxIdx        Furthest cursor reached, for error reporting.
+ * @property {string[]} expected    Token types acceptable at `maxIdx`.
+ * @property {Record<string, any>} grammar Rule name -> JSON Logic.
+ * @property {Map<string, any>|null} memo   Packrat cache, when enabled.
+ * @property {string[]} ruleNames   Rule-name stack, written by index, never popped.
+ * @property {number} ruleDepth     Live depth within `ruleNames`.
+ * @property {string[]|null} failureStack  Snapshot taken at the furthest failure.
+ * @property {boolean} track        Whether to record error-reporting detail.
+ * @property {number} steps         Combinator invocations, for the runaway guard.
+ * @property {number} maxSteps      0 disables the guard.
+ */
+
+/**
+ * @param {import('./lexer.js').Token[]} tokens
+ * @param {Record<string, any>} grammar
+ * @param {{ memo?: boolean, maxSteps?: number, track?: boolean }} [options]
+ * @returns {ParserState}
+ */
+export const createState = (tokens, grammar, options = {}) => ({
+  tokens,
+  idx: 0,
+  maxIdx: 0,
+  expected: [],
+  grammar,
+  memo: options.memo ? new Map() : null,
+  // Entering a rule is one array store rather than an object allocation, and
+  // the stack is snapshotted only on a furthest failure — by the time an error
+  // is built it would otherwise have unwound to just the start rule.
+  ruleNames: [],
+  ruleDepth: 0,
+  failureStack: null,
+  track: options.track === true,
+  steps: 0,
+  maxSteps: options.maxSteps || 0
+})
+
+/**
+ * Records that `expectation` would have been accepted at the cursor, keeping
+ * only the *furthest* position — the alternative that got deepest is almost
+ * always the one the author meant.
+ *
+ * Tracking is off during the first parse. `expect` fires on every failed token
+ * match, so the bookkeeping (acceptable tokens, rule stack) is most of the work
+ * in a backtracking grammar — slicing the rule stack per advance measured ~50x.
+ * On failure `parseTokens` re-runs with `track` on and builds the message from
+ * that; the parser is deterministic, so it lands in the same place.
+ *
+ * @param {ParserState} state
+ * @param {string} expectation
+ */
+export function expect (state, expectation) {
+  if (state.idx > state.maxIdx) {
+    state.maxIdx = state.idx
+    if (!state.track) return
+    // An array, not a Set: a handful of names, so a linear scan beats hashing.
+    state.expected = []
+    state.failureStack = state.ruleNames.slice(0, state.ruleDepth)
+  }
+  if (!state.track || state.idx !== state.maxIdx) return
+  if (!state.expected.includes(expectation)) state.expected.push(expectation)
+}
+
+export class ParseError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ token: import('./lexer.js').Token | null, expected: string[], ruleStack: string[] }} details
+   */
+  constructor (message, details) {
+    super(message)
+    this.name = 'ParseError'
+    this.token = details.token
+    this.expected = details.expected
+    this.ruleStack = details.ruleStack
+  }
+}
+
+/** Chevrotain-flavoured message built from the furthest failure. */
+const describeExpected = (expected) =>
+  expected.length === 0 ? 'nothing'
+    : expected.length === 1 ? expected[0]
+      : `one of [${expected.join(', ')}]`
+
+/**
+ * @param {ParserState} state
+ * @returns {ParseError}
+ */
+export function buildParseError (state) {
+  const token = state.tokens[state.maxIdx] || null
+  const expected = [...state.expected].sort()
+  const ruleStack = state.failureStack || state.ruleNames.slice(0, state.ruleDepth)
+
+  // Without line tracking there is no line to name, so report the offset.
+  const at = (t) => state.positions === 'offset'
+    ? `offset ${t.start}`
+    : `line ${t.line} column ${t.col}`
+  const found = token ? `--> ${token.image} <-- (${token.type}) at ${at(token)}` : 'end of input'
+
+  return new ParseError(
+    `Expecting ${describeExpected(expected)} but found ${found}`,
+    { token, expected, ruleStack }
+  )
+}

package/src/values.js

@@ -0,0 +1,67 @@
+// @ts-check
+'use strict'
+
+/**
+ * JSON Logic methods available inside semantic actions, beyond the engine's own.
+ *
+ * Deliberately a module of its own with no imports. It is needed in four places
+ * — `createParser`'s engine, the emitter's compile engine, and the engine a
+ * generated module builds when it still has one — and the last of those reaches
+ * it through `grammatik/runtime`, which must not grow a dependency on the
+ * planner or the analyzer to get here.
+ */
+
+/**
+ * `obj` — build an object whose keys are computed.
+ *
+ *   {"obj": [{"val": "op"}, [{"val": "left"}, {"val": "right"}]]}
+ *   -> {"+": [1, 2]}   when `op` is "+"
+ *
+ * This is the one thing a parser action does constantly that JSON Logic could
+ * not express. Building a node whose *type* comes from the input — `binary`,
+ * `func`, `call`, every "wrap this in an operator" helper in every grammar here
+ * — was the single most common reason to drop into JavaScript, and none of those
+ * helpers were doing anything a data form could not.
+ *
+ * Arguments are flat key/value pairs, so `{"obj": [k, v]}` is the common case and
+ * `{"obj": [k1, v1, k2, v2]}` builds two entries. `eachKey` already covers static
+ * keys; this covers the rest.
+ */
+const badArity = (length) =>
+  new Error(`obj expects an even number of arguments (key, value, ...), received ${length}`)
+
+const objectFrom = (args) => {
+  if (!Array.isArray(args) || args.length === 0 || args.length % 2 !== 0) {
+    throw badArity(Array.isArray(args) ? args.length : 1)
+  }
+  const result = {}
+  for (let i = 0; i < args.length; i += 2) result[args[i]] = args[i + 1]
+  return result
+}
+
+/**
+ * Emits `({[k]: v, [k]: v})` with each key and value compiled in place, so the
+ * whole thing is one object literal with no call into the engine.
+ *
+ * This hook is not an optimization. Without it the emitter cannot turn an action
+ * using `obj` into source, so the generated parser would fall back to shipping
+ * the action as data and carrying json-logic-engine — a new operator that
+ * quietly cost a grammar its engine-free build would be worse than no operator.
+ */
+const compileObject = (args, buildState) => {
+  if (!Array.isArray(args) || args.length === 0 || args.length % 2 !== 0) return false
+  const strings = ['({[']
+  const items = []
+  for (let i = 0; i < args.length; i += 2) {
+    items.push(args[i])
+    strings.push(']: ')
+    items.push(args[i + 1])
+    strings.push(i + 2 < args.length ? ', [' : '})')
+  }
+  return buildState.compile(strings, ...items)
+}
+
+/** @returns {Record<string, any>} */
+export const createValueMethods = () => ({
+  obj: { method: objectFrom, compile: compileObject }
+})