Peggy Parser Generator

Common errors

• Error: Cannot find module 'pegjs'

  cause You have migrated from PEG.js but have not updated all `require` or `import` statements to reference `peggy` instead.
  fix Globally replace `pegjs` with `peggy` in your project's source code and configuration files.

• ReferenceError: require is not defined

  cause You are attempting to use CommonJS `require()` syntax for Peggy imports within an ES Module (ESM) context in Node.js, or your generated parser code (pre-v5) is being run in an ESM context without proper transpilation.
  fix For Peggy imports, use `import ... from 'peggy';`. For generated parsers in v5+, ensure your project is configured for ESM or transpile the output if targeting an older CJS environment or browser.

• SyntaxError: 'SyntaxError' constructor should not have a return type.

  cause This specific TypeScript error indicates an incompatibility with older `peggy.d.ts` definitions (e.g., from v5.0.1 or v5.0.2) when using TypeScript to compile code that imports `SyntaxError` from 'peggy'.
  fix Update Peggy to the latest `5.x.x` patch version (e.g., 5.1.0) to get the corrected TypeScript definitions.

• TypeError: Cannot read properties of undefined (reading 'text')

  cause This often occurs within semantic actions (`{ return text(); }`) in your grammar when `text()` is called outside a rule that has matched any input or if the `text()` function isn't available in the current scope for some reason.
  fix Ensure `text()` is called within a rule's action block and that the rule has successfully matched some input. Verify that the `text()` function is correctly defined and accessible in the context of your generated parser's actions.

Warnings

• breaking Peggy v5.0.0 and later no longer supports ES5 for generated parser code. Generated code now requires ES2020 features (e.g., `const`, `let`). If you need to support earlier runtimes, you must use a transpiler like Babel.
  Fix: Transpile your generated parser code using Babel or a similar tool if targeting environments older than ES2020, or update your runtime to Node.js >=20.
• gotcha When migrating from PEG.js, all `require('pegjs')` or `import ... from 'pegjs'` statements must be updated to `require('peggy')` or `import ... from 'peggy'`. Similarly, any command-line usage of `pegjs` should be replaced with `peggy`.
  Fix: Replace all instances of `pegjs` with `peggy` in your code and build scripts.
• breaking As of v5.0.6, Peggy switched from `tsc` and `rollup` to `tsup` for its own code generation. This change might be user-visible as `tsup` injects different polyfills, potentially affecting the runtime behavior of Peggy itself if you rely on specific polyfills in a custom build pipeline.
  Fix: Review your build pipeline and any polyfill assumptions if you encounter unexpected runtime issues after upgrading to v5.0.6 or later, especially if you use Peggy programmatically.
• gotcha Peggy requires Node.js version 20 or higher. Running Peggy with older Node.js versions will result in errors.
  Fix: Ensure your development and production environments are running Node.js version 20 or newer.
• gotcha Previous versions (e.g., 5.0.1, 5.0.2) had TypeScript definition issues related to `SyntaxError` constructor and return types. While fixed in later patches, if you're stuck on an older 5.x patch, you might encounter type-checking problems.
  Fix: Upgrade to the latest `5.x.x` patch release to benefit from TypeScript definition fixes, such as `5.1.0` or newer.

Install

• npm install peggy npm
• yarn add peggy yarn
• pnpm add peggy pnpm

Imports

• generate
  wrong:

  const generate = require('peggy').generate;

  correct:

  import { generate } from 'peggy';

  The primary function for compiling a PEG grammar string into a parser. CommonJS `require` is still supported but ESM `import` is preferred for modern Node.js environments.
• SyntaxError
  wrong:

  import { PeggySyntaxError } from 'peggy';

  correct:

  import { SyntaxError } from 'peggy';

  The custom error class thrown by generated parsers when input does not match the grammar. While exported, it's typically caught from the parser's `parse` method.
• cli

  import { cli } from 'peggy';

  For programmatic access to Peggy's command-line interface functionalities, useful for custom build tools. Most users will invoke `peggy` directly from the command line.

Quickstart

This quickstart demonstrates how to define a simple arithmetic grammar, generate a parser using `peggy.generate`, and then use the generated parser to process an input string. It also illustrates how to catch and handle `SyntaxError` instances thrown by the parser.

import { generate } from 'peggy';

const grammar = `
  start = expression
  expression = term (('+' / '-') term)*
  term = factor (('*' / '/') factor)*
  factor = number / '(' expression ')'
  number 'number' = [0-9]+ { return parseInt(text()); }
`;

try {
  const parser = generate(grammar, { output: 'parser', format: 'es' });

  const result = parser.parse('1 + 2 * (3 - 4)');
  console.log('Parse successful:', result);

  // Example of a syntax error
  parser.parse('1 +');
} catch (e: any) {
  if (e.name === 'SyntaxError') {
    console.error(`Syntax Error at line ${e.location.start.line}, column ${e.location.start.column}: ${e.message}`);
  } else {
    console.error('An unexpected error occurred:', e);
  }
}