README.md

   1 # Acorn
   2
   3 A tiny, fast JavaScript parser written in JavaScript.
   4
   5 ## Community
   6
   7 Acorn is open source software released under an
   8 [MIT license](https://github.com/acornjs/acorn/blob/master/LICENSE).
   9
  10 You are welcome to
  11 [report bugs](https://github.com/acornjs/acorn/issues) or create pull
  12 requests on [github](https://github.com/acornjs/acorn). For questions
  13 and discussion, please use the
  14 [Tern discussion forum](https://discuss.ternjs.net).
  15
  16 ## Installation
  17
  18 The easiest way to install acorn is from [`npm`](https://www.npmjs.com/):
  19
  20 ```sh
  21 npm install acorn
  22 ```
  23
  24 Alternately, you can download the source and build acorn yourself:
  25
  26 ```sh
  27 git clone https://github.com/acornjs/acorn.git
  28 cd acorn
  29 npm install
  30 ```
  31
  32 ## Interface
  33
  34 **parse**`(input, options)` is the main interface to the library. The
  35 `input` parameter is a string, `options` can be undefined or an object
  36 setting some of the options listed below. The return value will be an
  37 abstract syntax tree object as specified by the [ESTree
  38 spec](https://github.com/estree/estree).
  39
  40 ```javascript
  41 let acorn = require("acorn");
  42 console.log(acorn.parse("1 + 1"));
  43 ```
  44
  45 When encountering a syntax error, the parser will raise a
  46 `SyntaxError` object with a meaningful message. The error object will
  47 have a `pos` property that indicates the string offset at which the
  48 error occurred, and a `loc` object that contains a `{line, column}`
  49 object referring to that same position.
  50
  51 Options can be provided by passing a second argument, which should be
  52 an object containing any of these fields:
  53
  54 - **ecmaVersion**: Indicates the ECMAScript version to parse. Must be
  55   either 3, 5, 6 (2015), 7 (2016), 8 (2017), 9 (2018) or 10 (2019, partial
  56   support). This influences support for strict mode, the set of
  57   reserved words, and support for new syntax features. Default is 7.
  58
  59   **NOTE**: Only 'stage 4' (finalized) ECMAScript features are being
  60   implemented by Acorn. Other proposed new features can be implemented
  61   through plugins.
  62
  63 - **sourceType**: Indicate the mode the code should be parsed in. Can be
  64   either `"script"` or `"module"`. This influences global strict mode
  65   and parsing of `import` and `export` declarations.
  66
  67 - **onInsertedSemicolon**: If given a callback, that callback will be
  68   called whenever a missing semicolon is inserted by the parser. The
  69   callback will be given the character offset of the point where the
  70   semicolon is inserted as argument, and if `locations` is on, also a
  71   `{line, column}` object representing this position.
  72
  73 - **onTrailingComma**: Like `onInsertedSemicolon`, but for trailing
  74   commas.
  75
  76 - **allowReserved**: If `false`, using a reserved word will generate
  77   an error. Defaults to `true` for `ecmaVersion` 3, `false` for higher
  78   versions. When given the value `"never"`, reserved words and
  79   keywords can also not be used as property names (as in Internet
  80   Explorer's old parser).
  81
  82 - **allowReturnOutsideFunction**: By default, a return statement at
  83   the top level raises an error. Set this to `true` to accept such
  84   code.
  85
  86 - **allowImportExportEverywhere**: By default, `import` and `export`
  87   declarations can only appear at a program's top level. Setting this
  88   option to `true` allows them anywhere where a statement is allowed.
  89
  90 - **allowAwaitOutsideFunction**: By default, `await` expressions can
  91   only appear inside `async` functions. Setting this option to
  92   `true` allows to have top-level `await` expressions. They are
  93   still not allowed in non-`async` functions, though.
  94
  95 - **allowHashBang**: When this is enabled (off by default), if the
  96   code starts with the characters `#!` (as in a shellscript), the
  97   first line will be treated as a comment.
  98
  99 - **locations**: When `true`, each node has a `loc` object attached
 100   with `start` and `end` subobjects, each of which contains the
 101   one-based line and zero-based column numbers in `{line, column}`
 102   form. Default is `false`.
 103
 104 - **onToken**: If a function is passed for this option, each found
 105   token will be passed in same format as tokens returned from
 106   `tokenizer().getToken()`.
 107
 108   If array is passed, each found token is pushed to it.
 109
 110   Note that you are not allowed to call the parser from the
 111   callback—that will corrupt its internal state.
 112
 113 - **onComment**: If a function is passed for this option, whenever a
 114   comment is encountered the function will be called with the
 115   following parameters:
 116
 117   - `block`: `true` if the comment is a block comment, false if it
 118     is a line comment.
 119   - `text`: The content of the comment.
 120   - `start`: Character offset of the start of the comment.
 121   - `end`: Character offset of the end of the comment.
 122
 123   When the `locations` options is on, the `{line, column}` locations
 124   of the comment’s start and end are passed as two additional
 125   parameters.
 126
 127   If array is passed for this option, each found comment is pushed
 128   to it as object in Esprima format:
 129
 130   ```javascript
 131   {
 132     "type": "Line" | "Block",
 133     "value": "comment text",
 134     "start": Number,
 135     "end": Number,
 136     // If `locations` option is on:
 137     "loc": {
 138       "start": {line: Number, column: Number}
 139       "end": {line: Number, column: Number}
 140     },
 141     // If `ranges` option is on:
 142     "range": [Number, Number]
 143   }
 144   ```
 145
 146   Note that you are not allowed to call the parser from the
 147   callback—that will corrupt its internal state.
 148
 149 - **ranges**: Nodes have their start and end characters offsets
 150   recorded in `start` and `end` properties (directly on the node,
 151   rather than the `loc` object, which holds line/column data. To also
 152   add a
 153   [semi-standardized](https://bugzilla.mozilla.org/show_bug.cgi?id=745678)
 154   `range` property holding a `[start, end]` array with the same
 155   numbers, set the `ranges` option to `true`.
 156
 157 - **program**: It is possible to parse multiple files into a single
 158   AST by passing the tree produced by parsing the first file as the
 159   `program` option in subsequent parses. This will add the toplevel
 160   forms of the parsed file to the "Program" (top) node of an existing
 161   parse tree.
 162
 163 - **sourceFile**: When the `locations` option is `true`, you can pass
 164   this option to add a `source` attribute in every node’s `loc`
 165   object. Note that the contents of this option are not examined or
 166   processed in any way; you are free to use whatever format you
 167   choose.
 168
 169 - **directSourceFile**: Like `sourceFile`, but a `sourceFile` property
 170   will be added (regardless of the `location` option) directly to the
 171   nodes, rather than the `loc` object.
 172
 173 - **preserveParens**: If this option is `true`, parenthesized expressions
 174   are represented by (non-standard) `ParenthesizedExpression` nodes
 175   that have a single `expression` property containing the expression
 176   inside parentheses.
 177
 178 **parseExpressionAt**`(input, offset, options)` will parse a single
 179 expression in a string, and return its AST. It will not complain if
 180 there is more of the string left after the expression.
 181
 182 **tokenizer**`(input, options)` returns an object with a `getToken`
 183 method that can be called repeatedly to get the next token, a `{start,
 184 end, type, value}` object (with added `loc` property when the
 185 `locations` option is enabled and `range` property when the `ranges`
 186 option is enabled). When the token's type is `tokTypes.eof`, you
 187 should stop calling the method, since it will keep returning that same
 188 token forever.
 189
 190 In ES6 environment, returned result can be used as any other
 191 protocol-compliant iterable:
 192
 193 ```javascript
 194 for (let token of acorn.tokenizer(str)) {
 195   // iterate over the tokens
 196 }
 197
 198 // transform code to array of tokens:
 199 var tokens = [...acorn.tokenizer(str)];
 200 ```
 201
 202 **tokTypes** holds an object mapping names to the token type objects
 203 that end up in the `type` properties of tokens.
 204
 205 **getLineInfo**`(input, offset)` can be used to get a `{line,
 206 column}` object for a given program string and offset.
 207
 208 ### The `Parser` class
 209
 210 Instances of the **`Parser`** class contain all the state and logic
 211 that drives a parse. It has static methods `parse`,
 212 `parseExpressionAt`, and `tokenizer` that match the top-level
 213 functions by the same name.
 214
 215 When extending the parser with plugins, you need to call these methods
 216 on the extended version of the class. To extend a parser with plugins,
 217 you can use its static `extend` method.
 218
 219 ```javascript
 220 var acorn = require("acorn");
 221 var jsx = require("acorn-jsx");
 222 var JSXParser = acorn.Parser.extend(jsx());
 223 JSXParser.parse("foo(<bar/>)");
 224 ```
 225
 226 The `extend` method takes any number of plugin values, and returns a
 227 new `Parser` class that includes the extra parser logic provided by
 228 the plugins.
 229
 230 ## Command line interface
 231
 232 The `bin/acorn` utility can be used to parse a file from the command
 233 line. It accepts as arguments its input file and the following
 234 options:
 235
 236 - `--ecma3|--ecma5|--ecma6|--ecma7|--ecma8|--ecma9|--ecma10`: Sets the ECMAScript version
 237   to parse. Default is version 9.
 238
 239 - `--module`: Sets the parsing mode to `"module"`. Is set to `"script"` otherwise.
 240
 241 - `--locations`: Attaches a "loc" object to each node with "start" and
 242   "end" subobjects, each of which contains the one-based line and
 243   zero-based column numbers in `{line, column}` form.
 244
 245 - `--allow-hash-bang`: If the code starts with the characters #! (as
 246   in a shellscript), the first line will be treated as a comment.
 247
 248 - `--compact`: No whitespace is used in the AST output.
 249
 250 - `--silent`: Do not output the AST, just return the exit status.
 251
 252 - `--help`: Print the usage information and quit.
 253
 254 The utility spits out the syntax tree as JSON data.
 255
 256 ## Existing plugins
 257
 258  - [`acorn-jsx`](https://github.com/RReverser/acorn-jsx): Parse [Facebook JSX syntax extensions](https://github.com/facebook/jsx)
 259
 260 Plugins for ECMAScript proposals:
 261
 262  - [`acorn-stage3`](https://github.com/acornjs/acorn-stage3): Parse most stage 3 proposals, bundling:
 263    - [`acorn-async-iteration`](https://github.com/acornjs/acorn-async-iteration): Parse [async iteration proposal](https://github.com/tc39/proposal-async-iteration)
 264    - [`acorn-bigint`](https://github.com/acornjs/acorn-bigint): Parse [BigInt proposal](https://github.com/tc39/proposal-bigint)
 265    - [`acorn-class-fields`](https://github.com/acornjs/acorn-class-fields): Parse [class fields proposal](https://github.com/tc39/proposal-class-fields)
 266    - [`acorn-dynamic-import`](https://github.com/kesne/acorn-dynamic-import): Parse [import() proposal](https://github.com/tc39/proposal-dynamic-import)
 267    - [`acorn-import-meta`](https://github.com/acornjs/acorn-import-meta): Parse [import.meta proposal](https://github.com/tc39/proposal-import-meta)
 268    - [`acorn-numeric-separator`](https://github.com/acornjs/acorn-numeric-separator): Parse [numeric separator proposal](https://github.com/tc39/proposal-numeric-separator)
 269    - [`acorn-private-methods`](https://github.com/acornjs/acorn-private-methods): parse [private methods, getters and setters proposal](https://github.com/tc39/proposal-private-methods)n