Peggy Documentation

To run the Peggy benchmark suite in a web browser, follow these steps from the Peggy root directory:

1. Ensure Node.js is installed.
2. Install all dependencies (including development dependencies):

   npm install

3. Start the benchmark suite web server:

   benchmark/server

4. Open your browser and navigate to http://localhost:8000/.
5. Click the Run button and wait for the results.

$ npm install
$ benchmark/server

Peggy version 1.x.x is API compatible with the most recent PEG.js release. To upgrade, follow these steps:

1. Uninstall pegjs and @types/pegjs (Peggy includes its own type definitions).
2. Replace all require("pegjs") or import ... from "pegjs" with require("peggy") or import ... from "peggy".
3. Update any scripts using the pegjs CLI to use peggy instead.

The Peggy documentation site is built using the Eleventy static site generator. To generate a production build of the documentation, use the build script.

npm run build

To measure the speed of parsers generated by Peggy on various inputs using Node.js, follow these steps from the Peggy root directory:

1. Install all dependencies (including development dependencies):

   npm install

2. Execute the benchmark suite:

   npm run benchmark

3. Wait for the results to be generated.

$ npm install
$ npm run benchmark

For local development, you can run a development server that watches for file changes and automatically rebuilds the documentation site. Use the start script to begin development.

npm run start

Peggy supports plugins to extend its functionality. You can provide plugins via the --plugin flag. Plugins can be specified as:

• An NPM module name.
• An absolute or relative file path.

Plugins must export a use() function (or be the default export containing a use() function).

# Example: Using an NPM plugin
peggy --plugin my-peggy-plugin grammar.peggy

# Example: Using a local plugin file
peggy --plugin ./plugins/my-local-plugin.js grammar.peggy

You can extend the Peggy compilation process by providing plugins via the options.plugins array in the generate method.

Each plugin is expected to have a .use(config, options) method. The config object passed to the plugin contains:

• parser: The Peggy parser.
• passes: A copy of the compiler passes.
• reservedWords: A copy of the reserved words list.

The options object (the same one passed to generate) is also passed to the plugin's .use method.

const peg = require("peggy");

const myPlugin = {
  use: (config, options) => {
    // Implement plugin logic using config and options
  }
};

const parser = peg.generate(grammar, {
  plugins: [myPlugin]
});

Peggy allows you to provide additional configuration options through external files. This is useful for complex setups that are cumbersome to pass via CLI flags.

Supported file types:

• JavaScript files (.js, .mjs, .cjs): The file should export a default object containing the options.
• JSON files: A standard JSON object containing the options.

Precedence Rules:

• Options provided directly on the command line take precedence over those in an extra options file.
• For multi-value options (like plugin), the values in the extra options file are additive (appended to the CLI values).
• For object-type options, the values from the file are merged into the existing object.

# Example: Using a JavaScript config file
# config.mjs
export default {
  format: 'es',
  output: 'parser.js'
};

# Command line
peggy --extra-options-file config.mjs grammar.peggy

The Peggy CLI allows you to compile grammar files into JavaScript parsers. You can provide one or multiple grammar files, which will be combined in the order provided. You can also read grammars from stdin using - or import them directly from npm packages using the npm:<packageName>/file.peggy syntax.

Basic Usage:

# Generate a parser from a file (outputs to <input_file>.js)
peggy grammar.peggy

# Generate a parser and specify output file
peggy grammar.peggy -o parser.js

# Read grammar from stdin
cat grammar.peggy | peggy - -o parser.js

# Import grammar from an npm dependency
peggy npm:my-package/grammar.peggy -o parser.js

Use the -w or --watch flag to monitor your grammar files. Peggy will generate the output immediately and then re-generate it whenever the input file (or the test file, if provided) changes.

peggy grammar.peggy -o parser.js --watch