cerxes/babel
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Rewrite README

Browse Source
This commit is contained in:
Marijn Haverbeke 2013-11-04 16:43:07 +01:00
parent 3b05fcf16c
commit 5ec47cf80d
2 changed files with 163 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

239
README.md
View File

@ -1,122 +1,205 @@
# Acorn
[acorn]: http://marijnhaverbeke.nl/acorn/
[range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678
A tiny, fast JavaScript parser, written completely in JavaScript.
## Invoking
## Installation
Acorn can be invoked in several ways.
The easiest way to install acorn is with [`npm`][npm].
- From a Node script.
- From the command line.
- From a browser script.
### Node script
To use acorn from a [Node](http://nodejs.org) script, install acorn as a package as usual using npm:
[npm]: http://npmjs.org
```sh
npm install acorn
```
Alternately, download the source and link to that:
Alternately, download the source.
```sh
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:
## Components
```javascript
var fs = require('fs'),
acorn = require('acorn');
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.
try
{
var code = fs.readFileSync(pathToFile, "utf8"),
ast = acorn.parse(code);
}
catch(e)
{
console.error(e.message);
process.exit(1);
}
```
### acorn.js
### Command line
This file contains the actual parser (and is what you get when you
`require("acorn")` in node.js).
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:
**`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].
```text
acorn [options] file
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.
Parses <file> and outputs the AST in JSON format.
[mozapi]: https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API
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.
```
- **`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.
### Browser script
- **`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`.
To use acorn in the browser, load `acorn.js` with a `<script>` tag:
- **`allowTrailingCommas`**: If `false`, the parser will not allow
trailing commas in array and object literals. Default is `true`.
```
<script src="acorn.js" type="text/javascript"></script>
```
- **`forbidReserved`**: If `true`, using a reserved word will generate
an error. Defaults to `false`.
Acorn is compatible with [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD), so you may also use loaders like [require.js](http://www.requirejs.org) to load acorn in the browser.
- **`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`.
Once acorn is loaded, you may use acorn within your own scripts by calling `acorn.parse` as illustrated in the Node example above.
- **`onComment`**: If a function is passed for this option, whenever a
comment is encountered the function will be called with the
following parameters:
## Options
- `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.
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.
When the `locations` options is on, the `{line, column}` locations
of the comment’s start and end are passed as two additional
parameters.
- **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
- **`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`.
- **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`
- **`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.
- **allowTrailingCommas**: If `false`, the parser will not allow trailing commas in array and object literals.
- **`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.
- **forbidReserved**: If `true`, using a reserved word will generate an error. *Default*: `false`
- **`directSourceFile`**: Like `sourceFile`, but the property will be
added directly to the nodes, rather than to a `loc` object.
- **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`
[range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678
- **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.
**`getLineInfo`**`(input, offset)` can be used to get a `{line,
column}` object for a given program string and character offset.
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`
**`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.
- **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`. *Default*: `false`
**`tokTypes`** holds an object mapping names to the token type objects
that end up in the `type` properties of tokens.
- **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`
### acorn_loose.js ###
- **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`
This file implements an error-tolerant parser. It exposes a single
function.
- **directSourceFile**: Like the `sourceFile` option, but adds a "sourceFile" attribute directly to every node, whether or not `locations` is `true`. *Default*: `null`
**`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.
## Errors
### util/walk.js ###
When an error occurs, acorn throws a `SyntaxError` with the following attributes:
Implements an abstract syntax tree walker. Will store its interface in
`acorn.walk` when used without a module system.
- **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.
**`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.

4
index.html
View File

@ -59,9 +59,9 @@ end]</code> array with the same numbers, set the <code>ranges</code> option to
passing the tree produced by parsing the first file as
<code>program</code> option in subsequent parses. This will add the
toplevel forms of the parsed file to the <code>Program</code> (top) node
of an existing parse tree.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">program</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">&#182;</a> </div> <p>When <code>location</code> is on, you can pass this to record the source
of an existing parse tree.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">program</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-12"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-12">&#182;</a> </div> <p>When <code>locations</code> is on, you can pass this to record the source
file in every node's <code>loc</code> object.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">sourceFile</span><span class="o">:</span> <span class="kc">null</span><span class="p">,</span></pre></div> </td> </tr> <tr id="section-13"> <td class="docs"> <div class="pilwrap"> <a class="pilcrow" href="#section-13">&#182;</a> </div> <p>This value, if given, is stored in every node, whether
<code>location</code> is on or off.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">directSourceFile</span><span class="o">:</span> <span class="kc">null</span>
<code>locations</code> is on or off.</p> </td> <td class="code"> <div class="highlight"><pre> <span class="nx">directSourceFile</span><span class="o">:</span> <span class="kc">null</span>
<span class="p">};</span>
<span class="kd">function</span> <span class="nx">setOptions</span><span class="p">(</span><span class="nx">opts</span><span class="p">)</span> <span class="p">{</span>