Acorn

A tiny, fast JavaScript parser, written completely in JavaScript.

Invoking

Acorn can be invoked in several ways.

• From a Node script.
• From the command line.
• From a browser script.

Node script

To use acorn from a Node script, install acorn as a package as usual using npm:

npm install acorn

Alternately, download the source and link to that:

git clone https://github.com/marijnh/acorn.git
cd acorn
npm link
cd /path/to/project
npm link acorn

Now you can require acorn in your node scripts. The main entrypoint to acorn is the parse function, which returns an object with the AST nodes:

var fs = require('fs'),
    acorn = require('acorn');

try
{
    var code = fs.readFileSync(pathToFile, "utf8"),
        ast = acorn.parse(code);
}
catch(e)
{
    console.error(e.message);
    process.exit(1);
}

Command line

To use acorn from the command line, use the acorn binary, which is installed when you use npm to install or link the acorn package. Alternately, you can execute bin/acorn directly. The syntax is as follows:

acorn [options] file

Parses <file> and outputs the AST in JSON format.

Options:
--ecma3|--ecma5     Sets the ECMAScript version to parse. Default is version 5.
--strictSemicolons  Prevents the parser from doing automatic semicolon insertion.
                    Statements that do not end in semicolons will generate an error.
--locations         Attaches a "loc" object to each node with "start" and "end" subobjects,
                    each of which contains the one-based line and zero-based column numbers
                    in {line, column} form.
--compact           No whitespace is used in the AST output.
--silent            Do not output the AST, just return the exit status.
--help              Print this usage information and quit.

Browser script

To use acorn in the browser, load acorn.js with a <script> tag:

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

Acorn is compatible with AMD, so you may also use loaders like require.js to load acorn in the browser.

Once acorn is loaded, you may use acorn within your own scripts by calling acorn.parse as illustrated in the Node example above.

Options

The optional second parameter to the parse function is an options object. Acorn supports a number of options that control its behavior and its output.

• ecmaVersion: Indicates the ECMAScript version to parse. Must be either 3 or 5. This influences support for strict mode, the set of reserved words, and support for getters and setter. Default: 5

• strictSemicolons: If true, prevents the parser from doing automatic semicolon insertion, and statements that do not end with a semicolon will generate an error. Default: false

• allowTrailingCommas: If false, the parser will not allow trailing commas in array and object literals.

• forbidReserved: If true, using a reserved word will generate an error. Default: false

• locations: When true, each node has a "loc" object attached with "start" and "end" subobjects, each of which contains the one-based line and zero-based column numbers in {line, column} form. Default: false

• onComment: If a function is passed for this option, whenever a comment is encountered the function will be called with the following parameters:

  • block: true if the comment is a block comment, false if it is a line comment.
  • text: The content of the comment.
  • start: Character offset of the start of the comment.
  • end: Character offset of the end of the comment.

  When the locations options is on, the {line, column} locations of the comment’s start and end are passed as two additional parameters. Default: null

• ranges: Nodes have their start and end characters offsets recorded in "start" and "end" properties (directly on the node, rather than the "loc" object, which holds line/column data. To also add a semi-standardized "range" property holding a [start, end] array with the same numbers, set the ranges option to true. Default: false

• program: It is possible to parse multiple files into a single AST by passing the tree produced by parsing the first file as the program option in subsequent parses. This will add the toplevel forms of the parsed file to the "Program" (top) node of an existing parse tree. Default: null

• sourceFile: When the locations option is true, you can pass this option to add a "sourceFile" attribute in every node’s "loc" object. Note that the contents of this option are not examined or processed in any way; you are free to use whatever format you choose. Default: null

• directSourceFile: Like the sourceFile option, but adds a "sourceFile" attribute directly to every node, whether or not locations is true. Default: null

Errors

When an error occurs, acorn throws a SyntaxError with the following attributes:

• message: A descriptive message of the error. The error message will end with (line:column), where line is the one-based line number on which the error occurred, and column is the zero-based column within that line.
• pos: The zero-based character position at which the error occurred.
• loc: An object in the form {line:N, column:N}, where line is the one-based line number on which the error occurred, and column is the zero-based column number within that line.
• raisedAt: The zero-based character position the parser had reached at the point where the error occurred.