[Pkg-javascript-commits] [node-acorn-jsx] 162/484: Rewrite README
Bastien Roucariès
rouca at moszumanska.debian.org
Sat Aug 19 14:20:20 UTC 2017
This is an automated email from the git hooks/post-receive script.
rouca pushed a commit to branch master
in repository node-acorn-jsx.
commit 5ec47cf80d76fa1fb68ea611b1faf36f83366029
Author: Marijn Haverbeke <marijnh at gmail.com>
Date: Mon Nov 4 16:43:07 2013 +0100
Rewrite README
---
README.md | 255 ++++++++++++++++++++++++++++++++++++++++---------------------
index.html | 4 +-
2 files changed, 171 insertions(+), 88 deletions(-)
diff --git a/README.md b/README.md
index 81488e7..f44bacf 100644
--- a/README.md
+++ b/README.md
@@ -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
-
-Acorn can be invoked in several ways.
-
-- From a Node script.
-- From the command line.
-- From a browser script.
+## Installation
-### Node script
+The easiest way to install acorn is with [`npm`][npm].
-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:
-
-```javascript
-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);
-}
-```
+## Components
-### Command line
+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.
-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.js
-```text
-acorn [options] file
+This file contains the actual parser (and is what you get when you
+`require("acorn")` in node.js).
-Parses <file> and outputs the AST in JSON format.
+**`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].
-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.
-```
+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.
-### Browser script
+[mozapi]: https://developer.mozilla.org/en-US/docs/SpiderMonkey/Parser_API
-To use acorn in the browser, load `acorn.js` with a `<script>` tag:
+- **`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.
-```
-<script src="acorn.js" type="text/javascript"></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`.
-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.
+- **`allowTrailingCommas`**: If `false`, the parser will not allow
+ trailing commas in array and object literals. Default is `true`.
-Once acorn is loaded, you may use acorn within your own scripts by calling `acorn.parse` as illustrated in the Node example above.
+- **`forbidReserved`**: If `true`, using a reserved word will generate
+ an error. Defaults to `false`.
-## Options
+- **`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`.
-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.
+- **`onComment`**: If a function is passed for this option, whenever a
+ comment is encountered the function will be called with the
+ following 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
+ - `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.
-- **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`
+ When the `locations` options is on, the `{line, column}` locations
+ of the comment’s start and end are passed as two additional
+ parameters.
-- **allowTrailingCommas**: If `false`, the parser will not allow trailing commas in array and object literals.
+- **`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`.
-- **forbidReserved**: If `true`, using a reserved word 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.
-- **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`
+- **`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.
-- **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.
+- **`directSourceFile`**: Like `sourceFile`, but the property will be
+ added directly to the nodes, rather than to a `loc` object.
- 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] "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:
+[range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678
-- **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.
+**`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.
diff --git a/index.html b/index.html
index c2892ec..18d4291 100644
--- a/index.html
+++ b/index.html
@@ -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">¶</a> </div> [...]
+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">¶</a> </div> [...]
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">¶</a> [...]
-<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>
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-javascript/node-acorn-jsx.git
More information about the Pkg-javascript-commits
mailing list