.config/coc/extensions/node_modules/coc-prettier/node_modules/espree/README.md

   1 [![npm version](https://img.shields.io/npm/v/espree.svg)](https://www.npmjs.com/package/espree)
   2 [![Build Status](https://travis-ci.org/eslint/espree.svg?branch=master)](https://travis-ci.org/eslint/espree)
   3 [![npm downloads](https://img.shields.io/npm/dm/espree.svg)](https://www.npmjs.com/package/espree)
   4 [![Bountysource](https://www.bountysource.com/badge/tracker?tracker_id=9348450)](https://www.bountysource.com/trackers/9348450-eslint?utm_source=9348450&utm_medium=shield&utm_campaign=TRACKER_BADGE)
   5
   6 # Espree
   7
   8 Espree started out as a fork of [Esprima](http://esprima.org) v1.2.2, the last stable published released of Esprima before work on ECMAScript 6 began. Espree is now built on top of [Acorn](https://github.com/ternjs/acorn), which has a modular architecture that allows extension of core functionality. The goal of Espree is to produce output that is similar to Esprima with a similar API so that it can be used in place of Esprima.
   9
  10 ## Usage
  11
  12 Install:
  13
  14 ```
  15 npm i espree
  16 ```
  17
  18 And in your Node.js code:
  19
  20 ```javascript
  21 const espree = require("espree");
  22
  23 const ast = espree.parse(code);
  24 ```
  25
  26 ## API
  27
  28 ### `parse()`
  29
  30 `parse` parses the given code and returns a abstract syntax tree (AST). It takes two parameters.
  31
  32 - `code` [string]() - the code which needs to be parsed.
  33 - `options (Optional)` [Object]() - read more about this [here](#options).
  34
  35 ```javascript
  36 const espree = require("espree");
  37
  38 const ast = espree.parse(code, options);
  39 ```
  40
  41 **Example :**
  42
  43 ```js
  44 const ast = espree.parse('let foo = "bar"', { ecmaVersion: 6 });
  45 console.log(ast);
  46 ```
  47
  48 <details><summary>Output</summary>
  49 <p>
  50
  51 ```
  52 Node {
  53   type: 'Program',
  54   start: 0,
  55   end: 15,
  56   body: [
  57     Node {
  58       type: 'VariableDeclaration',
  59       start: 0,
  60       end: 15,
  61       declarations: [Array],
  62       kind: 'let'
  63     }
  64   ],
  65   sourceType: 'script'
  66 }
  67 ```
  68
  69 </p>
  70 </details>
  71
  72 ### `tokenize()`
  73
  74 `tokenize` returns the tokens of a given code. It takes two parameters.
  75
  76 - `code` [string]() - the code which needs to be parsed.
  77 - `options (Optional)` [Object]() - read more about this [here](#options).
  78
  79 Even if `options` is empty or undefined or `options.tokens` is `false`, it assigns it to `true` in order to get the `tokens` array
  80
  81 **Example :**
  82
  83 ```js
  84 const tokens = espree.tokenize('let foo = "bar"', { ecmaVersion: 6 });
  85 console.log(tokens);
  86 ```
  87
  88 <details><summary>Output</summary>
  89 <p>
  90
  91 ```
  92 Token { type: 'Keyword', value: 'let', start: 0, end: 3 },
  93 Token { type: 'Identifier', value: 'foo', start: 4, end: 7 },
  94 Token { type: 'Punctuator', value: '=', start: 8, end: 9 },
  95 Token { type: 'String', value: '"bar"', start: 10, end: 15 }
  96 ```
  97
  98 </p>
  99 </details>
 100
 101 ### `version`
 102
 103 Returns the current `espree` version
 104
 105 ### `VisitorKeys`
 106
 107 Returns all visitor keys for traversing the AST from [eslint-visitor-keys](https://github.com/eslint/eslint-visitor-keys)
 108
 109 ### `latestEcmaVersion`
 110
 111 Returns the latest ECMAScript supported by `espree`
 112
 113 ### `supportedEcmaVersions`
 114
 115 Returns an array of all supported ECMAScript versions
 116
 117 ## Options
 118
 119 ```js
 120 const options = {
 121     // attach range information to each node
 122     range: false,
 123
 124     // attach line/column location information to each node
 125     loc: false,
 126
 127     // create a top-level comments array containing all comments
 128     comment: false,
 129
 130     // create a top-level tokens array containing all tokens
 131     tokens: false,
 132
 133     // Set to 3, 5 (default), 6, 7, 8, 9, 10, 11, or 12 to specify the version of ECMAScript syntax you want to use.
 134     // You can also set to 2015 (same as 6), 2016 (same as 7), 2017 (same as 8), 2018 (same as 9), 2019 (same as 10), 2020 (same as 11), or 2021 (same as 12) to use the year-based naming.
 135     ecmaVersion: 5,
 136
 137     // specify which type of script you're parsing ("script" or "module")
 138     sourceType: "script",
 139
 140     // specify additional language features
 141     ecmaFeatures: {
 142
 143         // enable JSX parsing
 144         jsx: false,
 145
 146         // enable return in global scope
 147         globalReturn: false,
 148
 149         // enable implied strict mode (if ecmaVersion >= 5)
 150         impliedStrict: false
 151     }
 152 }
 153 ```
 154
 155 ## Esprima Compatibility Going Forward
 156
 157 The primary goal is to produce the exact same AST structure and tokens as Esprima, and that takes precedence over anything else. (The AST structure being the [ESTree](https://github.com/estree/estree) API with JSX extensions.) Separate from that, Espree may deviate from what Esprima outputs in terms of where and how comments are attached, as well as what additional information is available on AST nodes. That is to say, Espree may add more things to the AST nodes than Esprima does but the overall AST structure produced will be the same.
 158
 159 Espree may also deviate from Esprima in the interface it exposes.
 160
 161 ## Contributing
 162
 163 Issues and pull requests will be triaged and responded to as quickly as possible. We operate under the [ESLint Contributor Guidelines](http://eslint.org/docs/developer-guide/contributing), so please be sure to read them before contributing. If you're not sure where to dig in, check out the [issues](https://github.com/eslint/espree/issues).
 164
 165 Espree is licensed under a permissive BSD 2-clause license.
 166
 167 ## Security Policy
 168
 169 We work hard to ensure that Espree is safe for everyone and that security issues are addressed quickly and responsibly. Read the full [security policy](https://github.com/eslint/.github/blob/master/SECURITY.md).
 170
 171 ## Build Commands
 172
 173 * `npm test` - run all linting and tests
 174 * `npm run lint` - run all linting
 175 * `npm run browserify` - creates a version of Espree that is usable in a browser
 176
 177 ## Differences from Espree 2.x
 178
 179 * The `tokenize()` method does not use `ecmaFeatures`. Any string will be tokenized completely based on ECMAScript 6 semantics.
 180 * Trailing whitespace no longer is counted as part of a node.
 181 * `let` and `const` declarations are no longer parsed by default. You must opt-in by using an `ecmaVersion` newer than `5` or setting `sourceType` to `module`.
 182 * The `esparse` and `esvalidate` binary scripts have been removed.
 183 * There is no `tolerant` option. We will investigate adding this back in the future.
 184
 185 ## Known Incompatibilities
 186
 187 In an effort to help those wanting to transition from other parsers to Espree, the following is a list of noteworthy incompatibilities with other parsers. These are known differences that we do not intend to change.
 188
 189 ### Esprima 1.2.2
 190
 191 * Esprima counts trailing whitespace as part of each AST node while Espree does not. In Espree, the end of a node is where the last token occurs.
 192 * Espree does not parse `let` and `const` declarations by default.
 193 * Error messages returned for parsing errors are different.
 194 * There are two addition properties on every node and token: `start` and `end`. These represent the same data as `range` and are used internally by Acorn.
 195
 196 ### Esprima 2.x
 197
 198 * Esprima 2.x uses a different comment attachment algorithm that results in some comments being added in different places than Espree. The algorithm Espree uses is the same one used in Esprima 1.2.2.
 199
 200 ## Frequently Asked Questions
 201
 202 ### Why another parser
 203
 204 [ESLint](http://eslint.org) had been relying on Esprima as its parser from the beginning. While that was fine when the JavaScript language was evolving slowly, the pace of development increased dramatically and Esprima had fallen behind. ESLint, like many other tools reliant on Esprima, has been stuck in using new JavaScript language features until Esprima updates, and that caused our users frustration.
 205
 206 We decided the only way for us to move forward was to create our own parser, bringing us inline with JSHint and JSLint, and allowing us to keep implementing new features as we need them. We chose to fork Esprima instead of starting from scratch in order to move as quickly as possible with a compatible API.
 207
 208 With Espree 2.0.0, we are no longer a fork of Esprima but rather a translation layer between Acorn and Esprima syntax. This allows us to put work back into a community-supported parser (Acorn) that is continuing to grow and evolve while maintaining an Esprima-compatible parser for those utilities still built on Esprima.
 209
 210 ### Have you tried working with Esprima?
 211
 212 Yes. Since the start of ESLint, we've regularly filed bugs and feature requests with Esprima and will continue to do so. However, there are some different philosophies around how the projects work that need to be worked through. The initial goal was to have Espree track Esprima and eventually merge the two back together, but we ultimately decided that building on top of Acorn was a better choice due to Acorn's plugin support.
 213
 214 ### Why don't you just use Acorn?
 215
 216 Acorn is a great JavaScript parser that produces an AST that is compatible with Esprima. Unfortunately, ESLint relies on more than just the AST to do its job. It relies on Esprima's tokens and comment attachment features to get a complete picture of the source code. We investigated switching to Acorn, but the inconsistencies between Esprima and Acorn created too much work for a project like ESLint.
 217
 218 We are building on top of Acorn, however, so that we can contribute back and help make Acorn even better.
 219
 220 ### What ECMAScript features do you support?
 221
 222 Espree supports all ECMAScript 2020 features and partially supports ECMAScript 2021 features.
 223
 224 Because ECMAScript 2021 is still under development, we are implementing features as they are finalized. Currently, Espree supports:
 225
 226 * [Logical Assignment Operators](https://github.com/tc39/proposal-logical-assignment)
 227 * [Numeric Separators](https://github.com/tc39/proposal-numeric-separator)
 228
 229 See [finished-proposals.md](https://github.com/tc39/proposals/blob/master/finished-proposals.md) to know what features are finalized.
 230
 231 ### How do you determine which experimental features to support?
 232
 233 In general, we do not support experimental JavaScript features. We may make exceptions from time to time depending on the maturity of the features.