README

WikiPEG is a recursive descent parser generator for Node.js, intended mostly to support Parsoid's complex needs. It is a fork of PEG.js with a new backend.

Features

• Simple and expressive grammar syntax
• Integrates both lexical and syntactical analysis
• Parsers have excellent error reporting out of the box
• Based on parsing expression grammar formalism — more powerful than traditional LL(k) and LR(k) parsers

Installation

Node.js

To use the wikipeg command, install WikiPEG globally:

$ npm install -g wikipeg

To use the JavaScript API, install WikiPEG locally:

$ npm install wikipeg

If you need both the wikipeg command and the JavaScript API, install WikiPEG both ways.

Generating a Parser

WikiPEG generates parser from a grammar that describes expected input and can specify what the parser returns (using semantic actions on matched parts of the input). Generated parser itself is a JavaScript object with a simple API.

Command Line

To generate a parser from your grammar, use the wikipeg command:

$ wikipeg arithmetics.pegjs

This writes parser source code into a file with the same name as the grammar file but with “.js” extension. You can also specify the output file explicitly:

$ wikipeg arithmetics.pegjs arithmetics-parser.js

If you omit both input and output file, standard input and output are used.

By default, the parser object is assigned to module.exports, which makes the output a Node.js module. You can assign it to another variable by passing a variable name using the -e/--export-var option. This may be helpful if you want to use the parser in browser environment.

You can tweak the generated parser with several options:

• --cache — makes the parser cache results, avoiding exponential parsing time in pathological cases but making the parser slower. See the cache option to PEG.buildParse and the Caching section below.
• --allowed-start-rules — comma-separated list of rules the parser will be allowed to start parsing from (default: the first rule in the grammar)
• --plugin — makes WikiPEG use a specified plugin (can be specified multiple times)
• --extra-options — additional options (in JSON format) to pass to PEG.buildParser
• --extra-options-file — file with additional options (in JSON format) to pass to PEG.buildParser
• --trace — makes the parser trace its progress
• --header-comment-file — file containing a well-formatted comment, used to customize the comment at the top of the generated file

JavaScript API

In Node.js, require the WikiPEG parser generator module:

var PEG = require("wikipeg");

In browser, include the WikiPEG library in your web page or application using the