[Pkg-javascript-commits] [node-acorn-jsx] 161/484: docco is wonderful, but it isn't exactly the most concise way of figuring out how to use acorn. Here's a real 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 3b05fcf16c8c75271e35a6916e4f80db7d0c6736
Author: Aparajita Fishman <aparajita at aparajita.com>
Date: Wed Oct 16 09:54:53 2013 -0400
docco is wonderful, but it isn't exactly the most concise way of figuring out how to use acorn. Here's a real README.
Fixed a typo in the options comments.
---
README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
acorn.js | 4 +--
2 files changed, 121 insertions(+), 4 deletions(-)
diff --git a/README.md b/README.md
index ff6eb88..81488e7 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,122 @@
# Acorn
-A tiny, fast JavaScript parser in JavaScript.
+[acorn]: http://marijnhaverbeke.nl/acorn/
+[range]: https://bugzilla.mozilla.org/show_bug.cgi?id=745678
-See http://marijnhaverbeke.nl/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](http://nodejs.org) script, install acorn as a package as usual using npm:
+
+```sh
+npm install acorn
+```
+
+Alternately, download the source and link to that:
+
+```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);
+}
+```
+
+### 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:
+
+```text
+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](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.
+
+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] "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.
diff --git a/acorn.js b/acorn.js
index c5788ff..0f525ee 100644
--- a/acorn.js
+++ b/acorn.js
@@ -94,11 +94,11 @@
// toplevel forms of the parsed file to the `Program` (top) node
// of an existing parse tree.
program: null,
- // When `location` is on, you can pass this to record the source
+ // When `locations` is on, you can pass this to record the source
// file in every node's `loc` object.
sourceFile: null,
// This value, if given, is stored in every node, whether
- // `location` is on or off.
+ // `locations` is on or off.
directSourceFile: null
};
--
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