# Acorn A tiny, fast JavaScript parser, written completely in JavaScript. ## Installation The easiest way to install acorn is with [`npm`][npm]. [npm]: http://npmjs.org ```sh npm install acorn ``` Alternately, download the source. ```sh git clone https://github.com/marijnh/acorn.git ``` ## Components When run in a CommonJS (node.js) or AMD environment, exported values appear in the interfaces exposed by the individual files, as usual. When loaded in the browser without any kind of module management, a single global object `acorn` will be defined, and all the exported properties will be added to that. ### acorn.js This file contains the actual parser (and is what you get when you `require("acorn")` in node.js). **parse**`(input, options)` is used to parse a JavaScript program. The `input` parameter is a string, `options` can be undefined or an object setting some of the options listed below. The return value will be an abstract syntax tree object as specified by the [Mozilla Parser API][mozapi]. When encountering a syntax error, the parser will raise a `SyntaxError` object with a meaningful message. The error object will have a `pos` property that indicates the character offset at which the error occurred, and a `loc` object that contains a `{line, column}` object referring to that same position. [mozapi]: https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API - **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 is 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. Defaults to `false`. - **allowTrailingCommas**: If `false`, the parser will not allow trailing commas in array and object literals. Default is `true`. - **forbidReserved**: If `true`, using a reserved word will generate an error. Defaults to `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 is `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. - **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] "range" property holding a `[start, end]` array with the same numbers, set the `ranges` option to `true`. - **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. - **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. - **directSourceFile**: Like `sourceFile`, but the property will be added directly to the nodes, rather than to a `loc` object. [range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678 **getLineInfo**`(input, offset)` can be used to get a `{line, column}` object for a given program string and character offset. **tokenize**`(input, options)` exports a primitive interface to Acorn's tokenizer. The function takes an input string and options similar to `parse` (though only some options are meaningful here), and returns a function that can be called repeatedly to read a single token, and returns a `{start, end, type, value}` object (with added `startLoc` and `endLoc` properties when the `locations` option is enabled). This object will be reused (updated) for each token, so you can't count on it staying stable. **tokTypes** holds an object mapping names to the token type objects that end up in the `type` properties of tokens. ### acorn_loose.js ### This file implements an error-tolerant parser. It exposes a single function. **parse_dammit**`(input, options)` takes the same arguments and returns the same syntax tree as the `parse` function in `acorn.js`, but never raises an error, and will do its best to parse syntactically invalid code in as meaningful a way as it can. It'll insert identifier nodes with name `"✖"` as placeholders in places where it can't make sense of the input. Depends on `acorn.js`, because it uses the same tokenizer. ### util/walk.js ### Implements an abstract syntax tree walker. Will store its interface in `acorn.walk` when used without a module system. **simple**`(node, visitors, base, state)` does a 'simple' walk over a tree. `node` should be the AST node to walk, and `visitors` an object with properties whose names correspond to node types in the [Mozilla Parser API][mozapi]. The properties should contain functions that will be called with the node object and, if applicable the state at that point. The last two arguments are optional. `base` is a walker algorithm, and `state` is a start state. The default walker will simply visit all statements and expressions and not produce a meaningful state. (An example of a use of state it to track scope at each point in the tree.) **recursive**`(node, state, functions, base)` does a 'recursive' walk, where the walker functions are responsible for continuing the walk on the child nodes of their target node. `state` is the start state, and `functions` should contain an object that maps node types to walker functions. Such functions are called with `(node, state, c)` arguments, and can cause the walk to continue on a sub-node by calling the `c` argument on it with `(node, state)` arguments. The optional `base` argument provides the fallback walker functions for node types that aren't handled in the `functions` object. If not given, the default walkers will be used. **make**`(functions, base)` builds a new walker object by using the walker functions in `functions` and filling in the missing ones by taking defaults from `base`. **findNodeAt**`(node, start, end, test, base, state)` tries to locate a node in a tree at the given start and/or end offsets, which satisfies the predicate `test`. `start` end `end` can be either `null` (as wildcard) or a number. `test` may be a string (indicating a node type) or a function that takes `(nodeType, node)` arguments and returns a boolean indicating whether this node is interesting. `base` and `state` are optional, and can be used to specify a custom walker. Nodes are tested from inner to outer, so if two nodes match the boundaries, the inner one will be preferred. **findNodeAround**`(node, pos, test, base, state)` is a lot like `findNodeAt`, but will match any node that exists 'around' (spanning) the given position. **findNodeAfter**`(node, pos, test, base, state)` is similar to `findNodeAround`, but will match all nodes *after* the given position (testing outer nodes before inner nodes). ## Command line interface The `bin/acorn` utility can be used to parse a file from the command line. It accepts as arguments its input file and the following 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 the usage information and quit. The utility spits out the syntax tree as JSON data.