PEG.js Parser Generator

Common errors

• TypeError: pegjs.buildParser is not a function

  cause Attempting to call the deprecated `buildParser` method instead of `generate`.
  fix Change `pegjs.buildParser(...)` to `pegjs.generate(...)`.

• Error: Infinite loop detected in grammar.

  cause The grammar contains a construct that could lead to infinite recursion during parsing, a check introduced in v0.9.0.
  fix Review grammar rules for left recursion or other patterns that could cause infinite loops. Restructure rules to ensure progress is made with each match.

• ReferenceError: PEG is not defined

  cause In a browser environment, the global API name changed from `PEG` to `peg` in v0.10.0, or the UMD/global output format was not correctly integrated.
  fix Use `peg` instead of `PEG` for the global variable. Ensure the generated parser script is included correctly and the format option (e.g., `globals`) is set appropriately during generation.

• SyntaxError: Expected [rule description] but [found token] found.

  cause The input string does not conform to the defined grammar rules at the specified location.
  fix Debug the input string and grammar. Use the error's `location` property (offset, line, column) to pinpoint the exact mismatch. Consider adding more robust error handling or `error()` calls within grammar actions.

Warnings

• breaking In v0.10.0, the primary API function `pegjs.buildParser` was renamed to `pegjs.generate`. Code using the old function name will break. Additionally, the global variable name for browser use changed from `PEG` to `peg`.
  Fix: Update calls from `pegjs.buildParser` to `pegjs.generate`. For browser environments, use `peg` instead of `PEG` if relying on global exports.
• breaking In v0.8.0, all internal identifiers in generated parser code were prefixed with `peg$` to discourage their direct use and avoid conflicts. Code that directly accessed non-prefixed internal variables within generated parsers will likely break.
  Fix: Avoid direct manipulation of internal parser state or variables within generated code. If absolutely necessary, adapt to the `peg$` prefix, but this is discouraged.
• gotcha The default output module format for generated parsers changed in v0.10.0. While CommonJS remains the default, explicitly specifying the `format` option (e.g., `format: 'commonjs'`, `format: 'umd'`, `format: 'globals'`) is now clearer and recommended, especially if distributing the generated parser.
  Fix: Always specify the `format` option in `pegjs.generate` (e.g., `{ format: 'commonjs' }`) or via the `--format` CLI option to ensure the desired output module system.
• gotcha PEG.js v0.10.0 was released in August 2016 and is no longer actively maintained. For ongoing development, modern JavaScript features, and TypeScript support, consider migrating to its direct successor, Peggy.js (`npm install peggy`), which is API compatible and actively maintained.
  Fix: Evaluate migrating to Peggy.js (`npm install peggy`) for an actively maintained and compatible parser generator.
• deprecated Tracing support, introduced in v0.9.0, was marked as experimental. Its API and behavior were subject to change, and users should not rely on its stability across minor versions.
  Fix: If using tracing features, be prepared for potential API changes. For v0.10.0, consult the specific documentation for its tracing implementation, if available.

Install

• npm install pegjs npm
• yarn add pegjs yarn
• pnpm add pegjs pnpm

Imports

• pegjs
  wrong:

  import pegjs from 'pegjs';

  correct:

  const pegjs = require('pegjs');

  PEG.js v0.10.0 is a CommonJS module. Direct `import` syntax is not supported without a transpiler like Babel or a bundler configured for CJS interop. For modern ES module usage, consider `peggy`.
• generate
  wrong:

  const parser = pegjs.buildParser(grammarString, options);

  correct:

  const parser = pegjs.generate(grammarString, options);

  The `pegjs.buildParser` function was renamed to `pegjs.generate` in v0.10.0. Using `buildParser` will result in an error in this version.
• parser.parse

  const result = myParser.parse('input string');

  The generated parser (e.g., `myParser`) is a function with a `.parse()` method. This method takes the input string and returns the parsed result or throws a `SyntaxError`.

Quickstart

This quickstart demonstrates how to use `pegjs` to define a simple arithmetic grammar, generate a parser at runtime, and then use that parser to evaluate expressions and catch parsing errors.

const pegjs = require('pegjs');

// Define a simple grammar for arithmetic expressions
const grammar = `
  start = expression

  expression = term (('+' / '-') term)* {
    return arguments[0].reduce((acc, current) => {
      const [op, val] = current;
      return op === '+' ? acc + val : acc - val;
    });
  }

  term = factor (('*' / '/') factor)* {
    return arguments[0].reduce((acc, current) => {
      const [op, val] = current;
      return op === '*' ? acc * val : acc / val;
    });
  }

  factor = number / '(' expression ')'

  number = [0-9]+ {
    return parseInt(text(), 10);
  }

  whitespace = [ \t\n\r]*
`;

// Generate the parser
try {
  const parser = pegjs.generate(grammar, { 
    output: 'parser', 
    format: 'commonjs', 
    optimize: 'speed' 
  });

  // Use the generated parser
  const input1 = "10 + 5 * (2 - 1)";
  const result1 = parser.parse(input1);
  console.log(`Input: "${input1}", Result: ${result1}`); // Expected: 15

  const input2 = "(100 / 2) - 15";
  const result2 = parser.parse(input2);
  console.log(`Input: "${input2}", Result: ${result2}`); // Expected: 35

  // Example of a parsing error
  const invalidInput = "10 + * 5";
  try {
    parser.parse(invalidInput);
  } catch (e) {
    console.error(`Error parsing "${invalidInput}": ${e.message}`);
  }

} catch (e) {
  console.error("Error generating parser: ", e.message);
}