Espree

Espree is an actively-maintained fork Esprima, a high performance, standard-compliant ECMAScript parser written in ECMAScript (also popularly known as JavaScript).

Features

Full support for ECMAScript 5.1 (ECMA-262)
Sensible syntax tree format compatible with Mozilla Parser AST
Optional tracking of syntax node location (index-based and line-column)
Heavily tested (> 650 unit tests) with full code coverage

Usage

Install:

npm i espree --save

And in your Node.js code:

var espree = require("espree");

var ast = espree.parse(code);

There is a second argument to parse() that allows you to specify various options:

var espree = require("espree");

var ast = espree.parse(code, {

    // attach range information to each node
    range: true,

    // attach line/column location information to each node
    loc: true,

    // create a top-level comments array containing all comments
    comments: true,

    // attach comments to the closest relevant node as leadingComments and
    // trailingComments
    attachComment: true,

    // create a top-level tokens array containing all tokens
    tokens: true,

    // try to continue parsing if an error is encountered, store errors in a
    // top-level errors array
    tolerant: true,

    // specify parsing mode (default is highest available)
    ecmascript: 6
});

Plans

Espree starts as a fork of Esprima v1.2.2, the last stable published released of Esprima before work on ECMAScript 6 began. Espree's first version is therefore v1.2.2 and is 100% compatible with Esprima v1.2.2 as drop-in replacement. The version number will be incremented based on semantic versioning as features and bug fixes are added.

The immediate plans are:

Move away from giant files and move towards small, modular files that are easier to manage.
Move towards CommonJS for all files and use browserify to create browser bundles.
Support ECMAScript version filtering, allowing users to specify which version the parser should work in (similar to Acorn's ecmaVersion property).
Add tests to track comment attachment.
Add well-thought-out features that are useful for tools developers.
Add full support for ECMAScript 6.
Add optional parsing of JSX.

Esprima Compatibility Going Forward

The primary goal is to produce the exact same AST structure as Esprima and Acorn, and that takes precedence over anything else. (The AST structure being the SpiderMonkey Parser API with JSX extensions.) Separate from that, Espree may deviate from what Esprima outputs in terms of where and how comments are attached, as well as what additional information is available on AST nodes. That is to say, Espree may add more things to the AST nodes than Esprima does but the overall AST structure produced will be the same.

Espree may also deviate from Esprima in the interface it exposes.

Frequent and Incremental Releases

Espree will not do giant releases. Releases will happen periodically as changes are made and incremental releases will be made towards larger goals. For instance, we will not have one big release for ECMAScript 6 support. Instead, we will implement ECMAScript 6, piece-by-piece, hiding those pieces behind an ecmaVersion property that you can opt-out of if you don't want to use those features.

Contributing

Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the ESLint Contributor Guidelines, so please be sure to read them before contributing. If you're not sure where to dig in, check out the issues.

Espree is licensed under a permissive BSD 3-clause license.

Build Commands

npm test - run all linting and tests
npm run lint - run all linting
npm run browserify - creates a version of Espree that is usable in a browser

xjamundx / espree