Core Parsing

/**
 * Create a new parser instance
 * @param rules - Grammar rules object (compiled grammar) or Grammar instance
 * @param start - Start symbol name (optional if using Grammar instance)
 * @param options - Parser configuration options
 */
class Parser {
  constructor(rules, start, options);
  constructor(grammar, options);
}

/**
 * Parser configuration options
 */
interface ParserOptions {
  /** Keep history for rewinding (default: false) */
  keepHistory?: boolean;
  /** Custom lexer instance (default: StreamLexer) */
  lexer?: object;
}

const nearley = require("nearley");

// Using compiled grammar rules
const compiledGrammar = require("./my-grammar.js");
const parser1 = new nearley.Parser(compiledGrammar);

// Using Grammar instance
const grammar = nearley.Grammar.fromCompiled(compiledGrammar);
const parser2 = new nearley.Parser(grammar);

// With options
const parser3 = new nearley.Parser(grammar, {
  keepHistory: true,
  lexer: customLexer
});

/**
 * Reserved token for indicating parse failure in postprocessors
 */
static Parser.fail: object;

/**
 * Feed a chunk of input to the parser
 * @param chunk - String to parse
 * @returns Parser instance for chaining
 * @throws Error if parsing fails
 */
feed(chunk: string): Parser;

const parser = new nearley.Parser(grammar);

try {
  // Parse in chunks
  parser.feed("hello");
  parser.feed(" world");
  
  // Or parse all at once
  parser.feed("complete input text");
  
  console.log("Parse results:", parser.results);
} catch (error) {
  console.error("Parse error:", error.message);
  console.error("Error at token index:", error.offset);
}

/**
 * Save current parser state
 * @returns Column representing the current parse state
 */
save(): Column;

/**
 * Restore parser to a previously saved state
 * @param column - Previously saved parse state
 */
restore(column: Column): void;

/**
 * Rewind parser to a specific token index (deprecated - use save/restore instead)
 * @param index - Token index to rewind to
 * @throws Error if keepHistory is not enabled
 * @deprecated Use save() and restore() methods instead
 */
rewind(index: number): void;

const parser = new nearley.Parser(grammar, { keepHistory: true });

// Parse some input
parser.feed("partial input");
const checkpoint = parser.save();

// Continue parsing
try {
  parser.feed(" more input");
} catch (error) {
  // Restore to checkpoint and try alternative
  parser.restore(checkpoint);
  parser.feed(" alternative input");
}

/**
 * Get all possible parse results
 * @returns Array of parse results (empty if no complete parses)
 */
finish(): any[];

/**
 * Parser instance properties
 */
interface Parser {
  /** Current parsing results */
  results: any[];
  /** Parse table (array of columns) */
  table: Column[];
  /** Current token index */
  current: number;
  /** Grammar being used */
  grammar: Grammar;
  /** Parser options */
  options: ParserOptions;
  /** Current lexer instance */
  lexer: object;
  /** Current lexer state */
  lexerState: object;
}

const parser = new nearley.Parser(grammar);

parser.feed("input text");

// Check results
if (parser.results.length === 0) {
  console.log("No valid parse found");
} else if (parser.results.length === 1) {
  console.log("Unique parse:", parser.results[0]);
} else {
  console.log("Ambiguous parse:", parser.results.length, "interpretations");
  parser.results.forEach((result, i) => {
    console.log(`Parse ${i + 1}:`, result);
  });
}

// Get final results explicitly
const finalResults = parser.finish();

/**
 * Generate error message for unexpected token
 * @param token - The problematic token
 * @returns Formatted error message with context
 */
reportError(token: object): string;

/**
 * Generate error message for lexer errors
 * @param lexerError - Error from lexer
 * @returns Formatted error message
 */
reportLexerError(lexerError: Error): string;

/**
 * Get display string for a grammar symbol
 * @param symbol - Grammar symbol to display
 * @returns Human-readable symbol description
 */
getSymbolDisplay(symbol: any): string;

const parser = new nearley.Parser(grammar);

try {
  parser.feed("invalid input");
} catch (error) {
  console.error("Parse failed:", error.message);
  
  // Error properties
  console.log("Error at offset:", error.offset);
  console.log("Problematic token:", error.token);
  
  // The error message includes:
  // - Line and column information
  // - Context around the error
  // - Expected tokens at that position
  // - Parse state stack trace
}

/**
 * Parse state in the Earley algorithm
 */
interface State {
  rule: Rule;
  dot: number;
  reference: number;
  data: any[];
  wantedBy: State[];
  isComplete: boolean;
}

/**
 * Column in the Earley parse table
 */
interface Column {
  grammar: Grammar;
  index: number;
  states: State[];
  wants: object;
  scannable: State[];
  completed: object;
}