Astring

A tiny and fast JavaScript code generator from an ESTree-compliant AST.

Key features:

• Supports ECMAScript versions 5 and 6.
• Works on ESTree-compliant ASTs such as the ones produced by Acorn.
• Runs both in a browser and in Node.
• Considerably faster than Escodegen.
• Smaller than Esotope and faster for small ASTs.
• No dependencies and small footprint (~12 KB minified, ~3 KB gziped).
• Output code is readable and executable.

Installation

The easiest way is to install it with the Node Package Manager:

npm install astring

Alternatively, checkout this repository and install the development dependencies to build the module file:

git clone https://github.com/davidbonnet/astring.git
cd astring
npm install

The path to the module file is dist/astring.min.js and can be linked to from an HTML webpage. When used in a browser environment, the module exposes a global variable astring:

<script src="astring.min.js" type="text/javascript"></script>

Usage

The astring module consists of a function that takes two arguments: node and options. It returns a string representing the rendered code of the provided AST node. The options are:

• indent: string to use for indentation (defaults to "\t")
• lineEnd: string to use for line endings (defaults to "\n")
• startingIndentLevel: indent level to start from (defaults to 0)
• comments: generate comments

Example

This example uses Acorn, a blazingly fast JavaScript parser and AST producer. It is the perfect companion of Astring.

// Import modules (unnecessary when run in a browser)
acorn = require( 'acorn' );
astring = require( 'astring' );

// Example code
var code = "let answer = 4 + 7 * 5 + 3;\n";

// Parse it into an AST
var ast = acorn.parse( code, { ecmaVersion: 6 } );

// Set formatting options
var options = {
    indent: '   ',
    lineEnd: '\n'
};

// Format it
var result = astring( ast, options );

// Check it
if ( code === result ) {
    console.log( 'It works !' );
} else {
    console.log( 'Something went wrong…' );
}

Command line interface

The bin/astring utility can be used to convert a JSON-formatted ESTree compliant AST of a JavaScript code. It accepts the following arguments:

• --indent: string to use as indentation (defaults to "\t")
• --lineEnd: string to use for line endings (defaults to "\n")
• --startingIndentLevel: indent level to start from (defaults to 0)

The utility reads the AST from stdin or from a provided list of files, and prints out the resulting code.

Example

As in the previous example, these examples use Acorn to get the JSON-formatted AST. This command pipes the AST output by Acorn from a script.js file to Astring and writes the formatted JavaScript code into a result.js file:

acorn --ecma6 script.js | astring --indent "  " > result.js

This command does the same, but reads the AST from an intermediary file:

acorn --ecma6 script.js > ast.json
astring --indent "  " ast.json > result.js

Benchmark

From the repository, you can run benchmarks that compare Astring against Escodegen and Esotope:

npm run benchmark

Building

All building scripts are defined in the package.json file and rely on the Node Package Manager. All commands must be run from within the root repository folder.

Production

The source code of Astring is written in JavaScript 6 and located at src/astring.js. It is compiled down to a minified JavaScript 5 file located at dist/astring.min.js using Browserify, Babel and UglifyJS. This is achieved by running:

npm install

If you are already using a JavaScript 6 to 5 compiler for your project, or a JavaScript 6 compliant interpreter, you can include the src/astring.js file directly.

A non-minified and source map free version can be obtained at dist/astring.js by running:

npm run build

Development

If you are working on Astring, you can use Watchify to build automatically at each modification a non-minified version (along with a source map for easy debugging) located at dist/astring.debug.js by running:

npm start

While making changes to Astring, make sure it passes the tests by running:

npm test

TODO

• Comments generation (version 0.3.x)
• More tests (patches)