From 5d7f4d7a237660cb350baa0d5f7e6b474d003e8d Mon Sep 17 00:00:00 2001 From: Marijn Haverbeke Date: Fri, 20 Mar 2015 21:01:05 +0100 Subject: [PATCH] Update README --- README.md | 58 +++++++++++++++++++++++++++++++++++----------------- src/index.js | 3 --- 2 files changed, 39 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 3ab7882203..a2f2a45b47 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![Build Status](https://travis-ci.org/marijnh/acorn.svg?branch=master)](https://travis-ci.org/marijnh/acorn) [![NPM version](https://img.shields.io/npm/v/acorn.svg)](https://www.npmjs.org/package/acorn) -[Author funding status: ![maintainer happiness](https://marijnhaverbeke.nl/fund/status_s.png)](https://marijnhaverbeke.nl/fund/) +[Author funding status: ![maintainer happiness](https://marijnhaverbeke.nl/fund/status_s.png?force)](https://marijnhaverbeke.nl/fund/) A tiny, fast JavaScript parser, written completely in JavaScript. @@ -31,10 +31,10 @@ recent than IE5) 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 +### Main parser -This file contains the actual parser (and is what you get when you -`require("acorn")` in node.js). +This is implemented in `dist/acorn.js`, 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 @@ -161,15 +161,16 @@ there is more of the string left after the expression. **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 -`loc` property when the `locations` option is enabled and `range` -property when the `ranges` option is enabled). +**tokenizer**`(input, options)` returns an object with a `getToken` +method that can be called repeatedly to get the next token, a `{start, +end, type, value}` object (with added `loc` property when the +`locations` option is enabled and `range` property when the `ranges` +option is enabled). When the token's type is `tokTypes.eof`, you +should stop calling the method, since it will keep returning that same +token forever. -In ES6 environment, returned result can be used as any other protocol-compliant iterable: +In ES6 environment, returned result can be used as any other +protocol-compliant iterable: ```javascript for (let token of acorn.tokenize(str)) { @@ -221,12 +222,11 @@ in a context with such a (see [#90](https://github.com/marijnh/acorn/issues/90) and [#123](https://github.com/marijnh/acorn/issues/123)). -The `bin/without_eval` script can be used to generate a version of -`acorn.js` that has the generated code inlined, and can thus run -without evaluating anything. In versions of this library downloaded -from NPM, this script will be available as `acorn_csp.js`. +The `dist/acorn_csp.js` file in the distribution (which is built +by the `bin/without_eval` script) has the generated code inlined, and +can thus run without evaluating anything. -### acorn_loose.js ### +### dist/acorn_loose.js ### This file implements an error-tolerant parser. It exposes a single function. @@ -239,10 +239,10 @@ 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 ### +### dist/walk.js ### Implements an abstract syntax tree walker. Will store its interface in -`acorn.walk` when used without a module system. +`acorn.walk` when loaded 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 @@ -316,3 +316,23 @@ options: - `--help`: Print the usage information and quit. The utility spits out the syntax tree as JSON data. + +## Build system + +Acorn is written in ECMAScript 6, as a set of small modules, in the +project's `src` directory, and compiled down to bigger ECMAScript 3 +files in `dist` using [Browserify](http://browserify.org) and +[Babel](http://babeljs.io/). If you are already using Babel, you can +consider including the modules directly. + +The command-line test runner (`npm test`) uses the ES6 modules. The +browser-based test page (`test/index.html`) uses the compiled modules. +The `bin/build-acorn.js` script builds the latter from the former. + +If you are working on Acorn, you'll probably want to try the code out +directly, without an intermediate build step. In your scripts, you can +register the Babel require shim like this: + + require("babelify/node_modules/babel-core/register") + +That will allow you to directly `require` the ES6 modules. diff --git a/src/index.js b/src/index.js index fdc329c1d8..dcd5855539 100644 --- a/src/index.js +++ b/src/index.js @@ -65,9 +65,6 @@ export function parseExpressionAt(input, pos, options) { // Acorn is organized as a tokenizer and a recursive-descent parser. // The `tokenize` export provides an interface to the tokenizer. -// Because the tokenizer is optimized for being efficiently used by -// the Acorn parser itself, this interface is somewhat crude and not -// very modular. export function tokenizer(input, options) { return parser(options, input)