@scinorandex/sparse 0.0.8 → 0.1.2

package/src/meta/selfhosted.ts

@@ -1,8 +1,17 @@
 import { RegexEngine, Slex } from "@scinorandex/slex";
+import { describeThrowable, syntheticGrammarToken } from "../meta/common";
 import { Result, Sparse } from "../index";
 import { selfhosted } from "./states";
-import { TableState } from "../parser";
-import { GrammarToken, GrammarTokenMetadata, GrammarTokenType, hydrateProduction, Production } from "./common";
+import { LR1ParserGraveError, TableState } from "../parser";
+import {
+  GrammarToken,
+  GrammarTokenMetadata,
+  GrammarTokenType,
+  hydrateProduction,
+  Production,
+  ValidateProductionsOptions,
+  validateProductions,
+} from "./common";
 
 export const grammarLexerGenerator = new Slex<GrammarTokenType, GrammarTokenMetadata>({
   EOF_TYPE: GrammarTokenType.EOF,
@@ -21,9 +30,12 @@ grammarLexerGenerator.addRule(
 grammarLexerGenerator.addRule("letter", "${lowercase} | ${uppercase}");
 grammarLexerGenerator.addRule("digit", "0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9");
 grammarLexerGenerator.addRule("alphanumeric", "${letter} | ${digit}");
+// Dashes are allowed inside identifiers (but not first) so that the autogenerated productions of a
+// "*" or "+" group, which are named "autogen-0", "autogen-1", ... survive a round trip through a
+// table file.
 grammarLexerGenerator.addRule(
   "identifier",
-  "(${letter} | $_) (${letter} | ${digit} | $_)*",
+  "(${letter} | $_) (${letter} | ${digit} | $_ | $-)*",
   GrammarTokenType.IDENTIFIER,
 );
 grammarLexerGenerator.addRule("colon", "$:", GrammarTokenType.COLON);
@@ -312,8 +324,15 @@ const reducers: { [key: string]: Reducer } = {
   },
 };
 
-export const tryBuildProductions = (lexer: LexerInterface | string): Result<Production[]> => {
-  if (typeof lexer === "string") lexer = grammarLexerGenerator.generate(lexer, () => ({}));
+export const tryBuildProductions = (
+  lexer: LexerInterface | string,
+  options: ValidateProductionsOptions = {},
+): Result<Production[]> => {
+  try {
+    if (typeof lexer === "string") lexer = grammarLexerGenerator.generate(lexer, () => ({}));
+  } catch (err) {
+    return { success: false, reason: describeThrowable(err), token: syntheticGrammarToken() };
+  }
 
   const parserGenerator = getSelfHostedParserGenerator();
   const parser = parserGenerator.generate(lexer as RegexEngine<GrammarTokenType, GrammarTokenMetadata>, {
@@ -322,19 +341,31 @@ export const tryBuildProductions = (lexer: LexerInterface | string): Result<Prod
     },
   });
 
-  const parsingResult = parser.parse().result as ProgramNode;
-  const productions = parsingResult.getProductions();
-  return { success: true, value: productions };
+  let programNode: ProgramNode;
+  try {
+    programNode = parser.parse().result as ProgramNode;
+  } catch (err) {
+    // The grammar parser has no error recovery, so a malformed grammar surfaces as a
+    // LR1ParserGraveError. Translate it into the Result failure every caller already handles.
+    if (err instanceof LR1ParserGraveError && err.currentToken != null)
+      return { success: false, reason: err.reason, token: err.currentToken as GrammarToken };
+    return { success: false, reason: describeThrowable(err), token: syntheticGrammarToken() };
+  }
+
+  return validateProductions(programNode.getProductions(), options);
 };
 
-interface LexerInterface {
+export interface LexerInterface {
   peekNextToken(): GrammarToken;
   getNextToken(): GrammarToken;
   hasNextToken(): boolean;
 }
 
-export const buildProductions = (lexer: LexerInterface | string): Production[] => {
-  const result = tryBuildProductions(lexer);
+export const buildProductions = (
+  lexer: LexerInterface | string,
+  options: ValidateProductionsOptions = {},
+): Production[] => {
+  const result = tryBuildProductions(lexer, options);
   if (result.success === false)
     throw new Error(
       `Encountered error "${result.reason}" while parsing grammar at ${result.token.line}:${result.token.column}`,

package/src/parser.ts

@@ -2,15 +2,27 @@ import { Slex, Token } from "@scinorandex/slex";
 import { generateStates } from "./generator";
 import { Stack } from "./utils/Stack";
 import { Result } from "./utils/Result";
-import { Production } from "./meta/common";
+import { GrammarToken, Production, ProductionWarning } from "./meta/common";
+import { loadGrammar, loadTable } from "./utils/loadFiles";
+import { validateTable } from "./table/validate";
 
 export type TableAction = { type: "shift" | "reduce" | "goto"; value: number };
 
 export class TableState {
   public readonly actions: Map<string, TableAction>;
 
-  constructor(actions = new Map<string, TableAction>()) {
+  /**
+   * The actions exactly as they were written in a table file (`"s12"`, `"r3"`, `"7"`), kept so that
+   * malformed entries can be reported with the text the user actually typed.
+   */
+  public readonly rawActions: Map<string, string>;
+
+  constructor(
+    actions = new Map<string, TableAction>(),
+    rawActions = new Map<string, string>(),
+  ) {
     this.actions = actions;
+    this.rawActions = rawActions;
   }
 
   public getTerminalAction(terminal: string): TableAction | undefined {
@@ -21,16 +33,41 @@ export class TableState {
     return this.actions.get(variable);
   }
 
+  /** Every terminal this state can consume, without the surrounding brackets, sorted. */
+  public getTerminalKeys(): string[] {
+    return this.getKeys("[", "]");
+  }
+
+  /** Every variable this state can reduce past, without the surrounding angle brackets, sorted. */
+  public getVariableKeys(): string[] {
+    return this.getKeys("<", ">");
+  }
+
+  private getKeys(prefix: string, suffix: string): string[] {
+    const keys: string[] = [];
+    for (const key of this.actions.keys())
+      if (key.startsWith(prefix) && key.endsWith(suffix))
+        keys.push(key.substring(prefix.length, key.length - suffix.length));
+    return keys.sort();
+  }
+
   toJSObject() {
     return Object.fromEntries(this.actions);
   }
 
   static fromJSObject(json: ReturnType<TableState["toJSObject"]>) {
-    return new TableState(new Map(Object.entries(json)));
+    const actions = new Map(Object.entries(json));
+    const rawActions = new Map(
+      [...actions].map(([key, action]) => [
+        key,
+        action.type === "goto" ? `${action.value}` : `${action.type === "shift" ? "s" : "r"}${action.value}`,
+      ]),
+    );
+    return new TableState(actions, rawActions);
   }
 }
 
-type ReducerType<TokenType, Metadata, Node> = (
+export type ReducerType<TokenType, Metadata, Node> = (
   newInput: { bag: any; name: string | null },
   oldInput: { input: LR1StackSymbol<TokenType, Metadata, Node>[]; index: number },
 ) => Node;
@@ -39,20 +76,50 @@ export type LR1StackSymbol<TokenType, Metadata, Node> =
   | { type: "token"; token: Token<TokenType, Metadata> }
   | { type: "node"; node: Node };
 
+export type SparseOptions<TokenType> = {
+  productions: Production[];
+  states: TableState[];
+  toStringifiedTokenType: (tokenType: TokenType) => string;
+  /**
+   * Cross-check the productions against the parsing table right away, so a stale table is reported
+   * here instead of as an opaque crash in the middle of a parse. Off by default.
+   */
+  validate?: boolean;
+  /** Name of the grammar file, used to make validation errors actionable. */
+  source?: string;
+};
+
+export type FromProductionsOptions<TokenType> = {
+  productions: Production[];
+  toStringifiedTokenType: (tokenType: TokenType) => string;
+  mode?: "lr1" | "lalr1";
+  /** Generating states can take a while for big grammars; set to true to silence the timing log. */
+  quiet?: boolean;
+  onWarning?: (warning: ProductionWarning) => void;
+  onProgress?: (statesGenerated: number) => void;
+};
+
 export class Sparse<TokenType, Metadata, Node> {
   public constructor(
-    public readonly options: {
-      productions: Production[];
-      states: TableState[];
-      toStringifiedTokenType: (tokenType: TokenType) => string;
-    },
-  ) {}
+    public readonly options: SparseOptions<TokenType>,
+  ) {
+    if (options.validate === true) {
+      const result = validateTable(options.productions, options.states, { source: options.source });
+      if (result.success === false)
+        throw new Error(`The parsing table does not match the grammar: ${result.reason}`);
+    }
+  }
 
-  public static tryFromProductions<TokenType, Metadata, Node>(options: {
-    productions: Production[];
-    toStringifiedTokenType: (tokenType: TokenType) => string;
-  }): Result<Sparse<TokenType, Metadata, Node>> {
-    const statesResult = generateStates(options.productions);
+  public static tryFromProductions<TokenType, Metadata, Node>(
+    options: FromProductionsOptions<TokenType>,
+  ): Result<Sparse<TokenType, Metadata, Node>> {
+    const startedAt = Date.now();
+
+    const statesResult = generateStates(options.productions, {
+      mode: options.mode,
+      onWarning: options.onWarning,
+      onProgress: options.onProgress,
+    });
     if (statesResult.success === false) return statesResult;
     const states = statesResult.value;
 
@@ -62,16 +129,63 @@ export class Sparse<TokenType, Metadata, Node> {
       toStringifiedTokenType: options.toStringifiedTokenType,
     });
 
+    if (options.quiet !== true) {
+      const elapsed = Date.now() - startedAt;
+      const label = options.mode === "lalr1" ? "LALR(1)" : "LR(1)";
+      console.error(`Sparse generated ${sparse.options.states.length} ${label} states in ${elapsed}ms`);
+    }
+
     return { success: true, value: sparse };
   }
 
-  public static fromProductions<TokenType, Metadata, Node>(options: {
-    productions: Production[];
-    toStringifiedTokenType: (tokenType: TokenType) => string;
-  }) {
+  public static fromProductions<TokenType, Metadata, Node>(options: FromProductionsOptions<TokenType>) {
     const result = Sparse.tryFromProductions<TokenType, Metadata, Node>(options);
-    if (result.success === false)
-      throw new Error(`Encountered error "${result.reason}" at ${result.token.line}:${result.token.column}`);
+    if (result.success === false) throw new SparseGrammarError(result.reason, result.token);
+    return result.value;
+  }
+
+  /** Builds a parser generator from a grammar file and a prebuilt parsing table file. */
+  public static async tryFromGrammarFile<TokenType, Metadata, Node>(options: {
+    grammarPath: string;
+    tablePath: string;
+    toStringifiedTokenType: (tokenType: TokenType) => string;
+    onWarning?: (warning: ProductionWarning) => void;
+    /** Set to false to skip cross-checking the table against the grammar. */
+    validate?: boolean;
+  }): Promise<Result<Sparse<TokenType, Metadata, Node>>> {
+    const productionsResult = await loadGrammar(options.grammarPath, { onWarning: options.onWarning });
+    if (productionsResult.success === false) return productionsResult;
+
+    const statesResult = await loadTable(options.tablePath, { productions: productionsResult.value });
+    if (statesResult.success === false) return statesResult;
+
+    if (options.validate !== false) {
+      const tableResult = validateTable(productionsResult.value, statesResult.value, {
+        source: options.tablePath,
+      });
+      if (tableResult.success === false) return tableResult;
+    }
+
+    return {
+      success: true,
+      value: new Sparse<TokenType, Metadata, Node>({
+        productions: productionsResult.value,
+        states: statesResult.value,
+        toStringifiedTokenType: options.toStringifiedTokenType,
+        source: options.grammarPath,
+      }),
+    };
+  }
+
+  public static async fromGrammarFile<TokenType, Metadata, Node>(options: {
+    grammarPath: string;
+    tablePath: string;
+    toStringifiedTokenType: (tokenType: TokenType) => string;
+    onWarning?: (warning: ProductionWarning) => void;
+    validate?: boolean;
+  }): Promise<Sparse<TokenType, Metadata, Node>> {
+    const result = await Sparse.tryFromGrammarFile<TokenType, Metadata, Node>(options);
+    if (result.success === false) throw new SparseGrammarError(result.reason, result.token);
     return result.value;
   }
 
@@ -97,6 +211,12 @@ export type ParserRecoveryFunction<TokenType, Metadata, Node> = (options: {
     success: true;
     token?: Token<TokenType, Metadata>;
   };
+  /**
+   * Pushes a token that the input did not contain (a synthesized semicolon, a closing brace, ...)
+   * onto both stacks, exactly as if the lexer had produced it. Unlike `finish({ newToken })`, which
+   * only hands the token back to the parser as a lookahead, this one actually shifts it.
+   */
+  insertToken: (token: Token<TokenType, Metadata>) => { success: false; reason: string } | undefined;
   states: TableState[];
 }) => { success: true; token?: Token<TokenType, Metadata> } | { success: false; reason: string };
 
@@ -106,38 +226,52 @@ export type ParserResult<TokenType, Metadata, Node> = {
   errors: ParserError<TokenType, Metadata>[];
 };
 
-class LR1Parser<TokenType, Metadata, Node> {
+export class LR1Parser<TokenType, Metadata, Node> {
   statesStack: Stack<number> = new Stack([0]);
   symbolsStack: Stack<LR1StackSymbol<TokenType, Metadata, Node>> = new Stack();
   exceptions: ParserError<TokenType, Metadata>[] = [];
 
   public constructor(
-    public readonly options: {
-      productions: Production[];
-      states: TableState[];
-      toStringifiedTokenType: (tokenType: TokenType) => string;
-    },
+    public readonly options: SparseOptions<TokenType>,
     public readonly reducer: ReducerType<TokenType, Metadata, Node>,
     public readonly recover: ParserRecoveryFunction<TokenType, Metadata, Node> | null,
     public readonly lexer: ReturnType<Slex<TokenType, Metadata>["generate"]>,
   ) {}
 
+  /**
+   * Clears the stacks and the collected errors so the parser can be handed to a fresh lexer.
+   * A parser instance consumes its lexer, so the usual way to parse a second input is to call
+   * `generator.generate(newLexer, options)` again.
+   */
+  public reset() {
+    this.statesStack = new Stack([0]);
+    this.symbolsStack = new Stack();
+    this.exceptions = [];
+  }
+
   public parse(): ParserResult<TokenType, Metadata, Node> {
     const { productions, states, toStringifiedTokenType } = this.options;
 
+    if (states.length === 0)
+      throw new LR1ParserGraveError("The parsing table is empty, so no token can be parsed", null as any);
+
+    const currentStates = () => {
+      const state = states[this.statesStack.peek()];
+      if (state == null)
+        throw new LR1ParserGraveError(
+          `The parsing table is out of sync with the grammar: state ${this.statesStack.peek()} does not exist (the table has ${states.length} states)`,
+          null as any,
+        );
+      return state;
+    };
+
     while (true) {
-      let currentState = this.statesStack.peek();
+      let currentState = currentStates();
       let token = this.lexer.peekNextToken();
-      let action = states[currentState].getTerminalAction(toStringifiedTokenType(token.type));
+      let action = currentState.getTerminalAction(toStringifiedTokenType(token.type));
 
       if (action == null) {
-        if (this.recover === null)
-          throw new LR1ParserGraveError(
-            `Invalid syntax. Expected ${[...states[currentState].actions.keys()].join(
-              ",",
-            )} but got ${toStringifiedTokenType(token.type)}`,
-            token,
-          );
+        if (this.recover === null) throw new LR1ParserGraveError(this.syntaxErrorMessage(currentState, token), token);
 
         const recoveryResult = this.recover({
           lexer: this.lexer,
@@ -147,22 +281,25 @@ class LR1Parser<TokenType, Metadata, Node> {
           addError: (reason: string) => this.exceptions.push({ message: reason, token: this.lexer.peekNextToken() }),
           crash: (reason: string) => ({ success: false, reason }),
           finish: (options?: { newToken: Token<TokenType, Metadata> }) => ({ success: true, token: options?.newToken }),
+          insertToken: (newToken: Token<TokenType, Metadata>) => this.insertToken(newToken),
           isSafe: () =>
-            states[this.statesStack.peek()].actions.has(`[${toStringifiedTokenType(this.lexer.peekNextToken().type)}]`),
+            currentStates().actions.has(`[${toStringifiedTokenType(this.lexer.peekNextToken().type)}]`),
         });
 
         if (recoveryResult.success === false) throw new LR1ParserGraveError(recoveryResult.reason, token);
 
         token = recoveryResult.token ?? this.lexer.peekNextToken();
-        currentState = this.statesStack.peek();
-        action = states[currentState].getTerminalAction(toStringifiedTokenType(token.type));
+        currentState = currentStates();
+        action = currentState.getTerminalAction(toStringifiedTokenType(token.type));
+
+        if (action == null) throw new LR1ParserGraveError(this.syntaxErrorMessage(currentState, token), token);
       }
 
       const fixedAction = action as TableAction;
       if (fixedAction.type === "shift") {
         // add current token to the stack and push the next state
         token = this.lexer.getNextToken();
-        this.statesStack.push(fixedAction.value);
+        this.pushState(fixedAction.value);
         this.symbolsStack.push({ type: "token", token: token });
       }
 
@@ -171,6 +308,12 @@ class LR1Parser<TokenType, Metadata, Node> {
         if (fixedAction.value === 0) break;
         const production = productions[fixedAction.value];
 
+        if (production == null)
+          throw new LR1ParserGraveError(
+            `The parsing table is out of sync with the grammar: it reduces by production ${fixedAction.value}, but the grammar only has ${productions.length} productions`,
+            token,
+          );
+
         // pop the stack and reduce by this production
         const popped: LR1StackSymbol<TokenType, Metadata, Node>[] = [];
         for (let i = 0; i < production.rhs.length; i++) {
@@ -198,17 +341,18 @@ class LR1Parser<TokenType, Metadata, Node> {
           const node = this.reducer(newInput, oldInput);
           this.symbolsStack.push({ type: "node", node });
         } catch (err) {
-          const input = JSON.stringify(popped, null, 2);
-          console.log(err);
+          const cause = err instanceof Error ? err.message : String(err);
+          const input = truncate(JSON.stringify(popped), 500);
           throw new LR1ParserGraveError(
-            `Error while performing reduction for production: ${productionIndex}. Reduction input: ${input}`,
+            `Error while performing the reduction for production ${productionIndex}${describeProduction(production)}: ${cause}\nReduction input: ${input}`,
             token,
+            err instanceof Error ? err : undefined,
           );
         }
 
         // get the top node and figure out what state to add to state stack
         const topNode = this.statesStack.peek();
-        const gotoAction = states[topNode].getVariableAction(production.identifier);
+        const gotoAction = currentStates().getVariableAction(production.identifier);
 
         if (gotoAction == undefined)
           throw new LR1ParserGraveError(
@@ -221,21 +365,89 @@ class LR1Parser<TokenType, Metadata, Node> {
             token,
           );
 
-        this.statesStack.push(gotoAction.value);
+        this.pushState(gotoAction.value);
       }
     }
 
+    // A table can accept the empty input by reducing to production 0 straight away, in which case
+    // nothing was ever shifted and there is no tree to hand back.
+    if (this.symbolsStack.isEmpty) return { result: null, errors: this.exceptions };
+
     const top = this.symbolsStack.peek();
     return { result: top.type === "node" ? top.node : null, errors: this.exceptions };
   }
+
+  private pushState(state: number) {
+    if (state === undefined || this.options.states[state] == null)
+      throw new LR1ParserGraveError(
+        `The parsing table is out of sync with the grammar: it points at state ${state}, but the table only has ${this.options.states.length} states`,
+        null as any,
+      );
+    this.statesStack.push(state);
+  }
+
+  /** Shifts a token that was not in the input, used by error recovery. */
+  private insertToken(token: Token<TokenType, Metadata>): { success: false; reason: string } | undefined {
+    const state = this.options.states[this.statesStack.peek()];
+    const action = state?.getTerminalAction(this.options.toStringifiedTokenType(token.type));
+
+    if (action == null)
+      return {
+        success: false,
+        reason: `Cannot insert ${this.options.toStringifiedTokenType(token.type)} here: state ${
+          this.statesStack.peek()
+        } does not accept it. Expected ${state?.getTerminalKeys().join(", ") ?? "nothing"}`,
+      };
+
+    if (action.type !== "shift")
+      return {
+        success: false,
+        reason: `Cannot insert ${this.options.toStringifiedTokenType(
+          token.type,
+        )} here: state ${this.statesStack.peek()} reduces on it instead of shifting it`,
+      };
+
+    this.pushState(action.value);
+    this.symbolsStack.push({ type: "token", token });
+    return undefined;
+  }
+
+  private syntaxErrorMessage(state: TableState, token: Token<TokenType, Metadata>) {
+    const expected = state.getTerminalKeys();
+    const got = this.options.toStringifiedTokenType(token.type);
+    const lexeme = token.lexeme === "" ? "" : ` ("${token.lexeme}")`;
+    return (
+      `Invalid syntax at ${token.line}:${token.column}: got ${got}${lexeme}, but expected ${
+        expected.length === 0 ? "the end of the input" : `one of [${expected.join("], [")}]`
+      }`
+    );
+  }
 }
 
 export class LR1ParserGraveError<TokenType, Metadata> extends Error {
   constructor(
     public readonly reason: string,
-    public readonly currentToken: Token<TokenType, Metadata>,
+    public readonly currentToken: Token<TokenType, Metadata> | null,
     err?: Error,
   ) {
-    super(reason);
+    super(reason, err === undefined ? undefined : { cause: err });
+    this.name = "LR1ParserGraveError";
   }
 }
+
+/** A grammar (or table) problem found before parsing started, always tied to a place in the file. */
+export class SparseGrammarError extends Error {
+  constructor(
+    public readonly reason: string,
+    public readonly token: GrammarToken,
+  ) {
+    super(`Encountered error "${reason}" at ${token.line}:${token.column}`);
+    this.name = "SparseGrammarError";
+  }
+}
+
+const truncate = (value: string, max: number) =>
+  value.length <= max ? value : `${value.slice(0, max)}... (${value.length} characters)`;
+
+const describeProduction = (production: Production) =>
+  production.name == null ? ` (${production.identifier})` : ` ("${production.name}")`;

package/src/table/selfhosted.ts

@@ -1,7 +1,9 @@
-import { GrammarToken } from "../meta/common";
+import { GrammarToken, Production, describeThrowable, syntheticGrammarToken } from "../meta/common";
 import { BaseNode, getSelfHostedParserGenerator, grammarLexerGenerator, ListNode } from "../meta/selfhosted";
-import { TableAction, TableState } from "../parser";
+import { LR1ParserGraveError, TableAction, TableState } from "../parser";
 import { selfhosted } from "./states";
+import { Result } from "../utils/Result";
+import { TableFormatWarning, validateTableStates } from "./validate";
 
 class StateNode extends BaseNode {
   constructor(public readonly items: ListNode<ItemNode>) {
@@ -10,9 +12,11 @@ class StateNode extends BaseNode {
 
   toTableState(): TableState {
     const state = new TableState();
-    for (const item of this.items.getItems()) {
+    // The item list is built right-recursively (rest.add(item)), so it comes out reversed.
+    for (const item of this.items.getItemsReversed()) {
       const key = item.type === "terminal" ? `[${item.name.lexeme}]` : `<${item.name.lexeme}>`;
       state.actions.set(key, item.action);
+      state.rawActions.set(key, item.rawAction);
     }
     return state;
   }
@@ -23,6 +27,7 @@ class ItemNode extends BaseNode {
     public readonly type: "terminal" | "variable",
     public readonly name: GrammarToken,
     public readonly action: TableAction,
+    public readonly rawAction: string,
   ) {
     super();
   }
@@ -46,22 +51,53 @@ const reducers: { [key: string]: Reducer } = {
       type: bag.action.lexeme.startsWith("s") ? "shift" : "reduce",
       value: parseInt(bag.action.lexeme.substring(1)),
     };
-    return new ItemNode("terminal", bag.name, action);
+    return new ItemNode("terminal", bag.name, action, bag.action.lexeme);
   },
 
   variable: (bag: { name: GrammarToken; state: GrammarToken }) => {
     const action: TableAction = { type: "goto", value: parseInt(bag.state.lexeme) };
-    return new ItemNode("variable", bag.name, action);
+    return new ItemNode("variable", bag.name, action, bag.state.lexeme);
   },
 };
 
-export const buildStates = (grammar: string): TableState[] => {
-  const lexer = grammarLexerGenerator.generate(grammar, () => ({}));
+export type BuildStatesOptions = {
+  /** Pass the grammar's productions to also check every "reduce" action against them. */
+  productions?: Production[];
+  /** Name of the file the table was read from, used to make error messages actionable. */
+  source?: string;
+  onWarning?: (warning: TableFormatWarning) => void;
+};
+
+/**
+ * Reads a parsing table written by the CLI (`sparse --input=grammar.txt --output=table.txt`).
+ * Returns a `Result` instead of throwing so that table problems can be reported alongside the
+ * offending grammar line.
+ */
+export const tryBuildStates = (table: string, options: BuildStatesOptions = {}): Result<TableState[]> => {
+  const lexer = grammarLexerGenerator.generate(table, () => ({}));
   const parserGenerator = getSelfHostedParserGenerator(selfhosted as any);
-  const parser = parserGenerator.generate(lexer, {
-    reducer: ({ bag, name }) => reducers[name ?? ""](bag),
-  });
 
-  const parsingResult = (parser.parse().result as ListNode<StateNode>).getItemsReversed();
-  return parsingResult.map((state) => state.toTableState());
+  let states: ListNode<StateNode>;
+  try {
+    const parser = parserGenerator.generate(lexer, {
+      reducer: ({ bag, name }) => reducers[name ?? ""](bag),
+    });
+    states = parser.parse().result as ListNode<StateNode>;
+  } catch (err) {
+    if (err instanceof LR1ParserGraveError && err.currentToken != null)
+      return { success: false, reason: err.reason, token: err.currentToken as GrammarToken };
+    return { success: false, reason: describeThrowable(err), token: syntheticGrammarToken() };
+  }
+
+  const tableStates = states.getItemsReversed().map((state) => state.toTableState());
+  return validateTableStates(tableStates, options);
+};
+
+export const buildStates = (table: string, options: BuildStatesOptions = {}): TableState[] => {
+  const result = tryBuildStates(table, options);
+  if (result.success === false)
+    throw new Error(
+      `Encountered error "${result.reason}" while parsing the parsing table at ${result.token.line}:${result.token.column}`,
+    );
+  return result.value;
 };