You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you want to use your own parser and provide additional capabilities for your rules, you can specify your own custom parser. If a `parseForESLint` method is exposed on the parser, this method will be used to parse the code. Otherwise, the `parse` method will be used. Both methods should take in the source code as the first argument, and an optional configuration object as the second argument (provided as `parserOptions` in a config file). The `parse` method should simply return the AST. The `parseForESLint` method should return an object that contains the required property `ast`and optional properties `services`, `scopeManager`, and `visitorKeys`.
11
+
ESLint custom parsers let you extend ESLint to support linting new non-standard JavaScript language features or custom syntax in your code. A parser is responsible for taking your code and transforming it into an abstract syntax tree (AST) that ESLint can then analyze and lint.
12
12
13
-
*`ast` should contain the AST.
14
-
*`services` can contain any parser-dependent services (such as type checkers for nodes). The value of the `services` property is available to rules as `context.parserServices`. Default is an empty object.
15
-
*`scopeManager` can be a [ScopeManager](./scope-manager-interface) object. Custom parsers can use customized scope analysis for experimental/enhancement syntaxes. Default is the `ScopeManager` object which is created by [eslint-scope](https://github.com/eslint/eslint-scope).
16
-
* Support for `scopeManager` was added in ESLint v4.14.0. ESLint versions which support `scopeManager` will provide an `eslintScopeManager: true` property in `parserOptions`, which can be used for feature detection.
17
-
*`visitorKeys` can be an object to customize AST traversal. The keys of the object are the type of AST nodes. Each value is an array of the property names which should be traversed. Default is [KEYS of `eslint-visitor-keys`](https://github.com/eslint/eslint-visitor-keys#evkkeys).
18
-
* Support for `visitorKeys` was added in ESLint v4.14.0. ESLint versions which support `visitorKeys` will provide an `eslintVisitorKeys: true` property in `parserOptions`, which can be used for feature detection.
13
+
## Creating a Custom Parser
19
14
20
-
You can find an ESLint parser project [here](https://github.com/typescript-eslint/typescript-eslint).
15
+
A custom parser is a JavaScript object with either a `parse` or `parseForESLint` method. The `parse` method only returns the AST, whereas `parseForESLint` also returns additional values that let the parser customize the behavior of ESLint even more.
21
16
22
-
```json
23
-
{
24
-
"parser": "./path/to/awesome-custom-parser.js"
25
-
}
26
-
```
17
+
Both methods should take in the source code as the first argument, and an optional configuration object as the second argument, which is provided as [`parserOptions`](../use/configure/language-options#specifying-parser-options) in a configuration file.
27
18
28
19
```javascript
29
-
var espree =require("espree");
30
-
// awesome-custom-parser.js
31
-
exports.parseForESLint=function(code, options) {
32
-
return {
33
-
ast:espree.parse(code, options),
34
-
services: {
35
-
foo:function() {
36
-
console.log("foo");
37
-
}
38
-
},
39
-
scopeManager:null,
40
-
visitorKeys:null
41
-
};
20
+
// customParser.js
21
+
22
+
constespree=require("espree");
23
+
24
+
// Logs the duration it takes to parse each file.
25
+
functionparse(code, options) {
26
+
constlabel=`Parsing file "${options.filePath}"`;
27
+
console.time(label);
28
+
constast=espree.parse(code, options);
29
+
console.timeEnd(label);
30
+
return ast; // Only the AST is returned.
42
31
};
43
32
33
+
module.exports= { parse };
44
34
```
45
35
46
-
## The AST specification
36
+
## `parse` Return Object
37
+
38
+
The `parse` method should simply return the [AST](#ast-specification) object.
39
+
40
+
## `parseForESLint` Return Object
41
+
42
+
The `parseForESLint` method should return an object that contains the required property `ast` and optional properties `services`, `scopeManager`, and `visitorKeys`.
43
+
44
+
*`ast` should contain the [AST](#ast-specification) object.
45
+
*`services` can contain any parser-dependent services (such as type checkers for nodes). The value of the `services` property is available to rules as `context.parserServices`. Default is an empty object.
46
+
*`scopeManager` can be a [ScopeManager](./scope-manager-interface) object. Custom parsers can use customized scope analysis for experimental/enhancement syntaxes. The default is the `ScopeManager` object which is created by [eslint-scope](https://github.com/eslint/eslint-scope).
47
+
* Support for `scopeManager` was added in ESLint v4.14.0. ESLint versions that support `scopeManager` will provide an `eslintScopeManager: true` property in `parserOptions`, which can be used for feature detection.
48
+
*`visitorKeys` can be an object to customize AST traversal. The keys of the object are the type of AST nodes. Each value is an array of the property names which should be traversed. The default is [KEYS of `eslint-visitor-keys`](https://github.com/eslint/eslint-visitor-keys#evkkeys).
49
+
* Support for `visitorKeys` was added in ESLint v4.14.0. ESLint versions that support `visitorKeys` will provide an `eslintVisitorKeys: true` property in `parserOptions`, which can be used for feature detection.
50
+
51
+
## AST Specification
47
52
48
53
The AST that custom parsers should create is based on [ESTree](https://github.com/estree/estree). The AST requires some additional properties about detail information of the source code.
49
54
50
-
### All nodes:
55
+
### All Nodes
51
56
52
57
All nodes must have `range` property.
53
58
54
59
*`range` (`number[]`) is an array of two numbers. Both numbers are a 0-based index which is the position in the array of source code characters. The first is the start position of the node, the second is the end position of the node. `code.slice(node.range[0], node.range[1])` must be the text of the node. This range does not include spaces/parentheses which are around the node.
55
-
*`loc` (`SourceLocation`) must not be `null`. [The `loc` property is defined as nullable by ESTree](https://github.com/estree/estree/blob/25834f7247d44d3156030f8e8a2d07644d771fdb/es5.md#node-objects), but ESLint requires this property. On the other hand,`SourceLocation#source` property can be `undefined`. ESLint does not use the `SourceLocation#source` property.
60
+
*`loc` (`SourceLocation`) must not be `null`. [The `loc` property is defined as nullable by ESTree](https://github.com/estree/estree/blob/25834f7247d44d3156030f8e8a2d07644d771fdb/es5.md#node-objects), but ESLint requires this property. The`SourceLocation#source` property can be `undefined`. ESLint does not use the `SourceLocation#source` property.
56
61
57
-
The `parent` property of all nodes must be rewritable. ESLint sets each node's `parent` property to its parent node while traversing, before any rules have access to the AST.
62
+
The `parent` property of all nodes must be rewritable. Before any rules have access to the AST, ESLint sets each node's `parent` property to its parent node while traversing.
58
63
59
-
### The `Program`node:
64
+
### The `Program`Node
60
65
61
-
The `Program` node must have `tokens` and `comments` properties. Both properties are an array of the below Token interface.
66
+
The `Program` node must have `tokens` and `comments` properties. Both properties are an array of the below `Token` interface.
62
67
63
68
```ts
64
69
interfaceToken {
65
70
type:string;
66
71
loc:SourceLocation;
67
-
range: [number, number]; // See "All nodes:" section for details of `range` property.
72
+
// See the "All Nodes" section for details of the `range` property.
73
+
range: [number, number];
68
74
value:string;
69
75
}
70
76
```
@@ -74,8 +80,72 @@ interface Token {
74
80
75
81
The range indexes of all tokens and comments must not overlap with the range of other tokens and comments.
76
82
77
-
### The `Literal`node:
83
+
### The `Literal`Node
78
84
79
85
The `Literal` node must have `raw` property.
80
86
81
87
*`raw` (`string`) is the source code of this literal. This is the same as `code.slice(node.range[0], node.range[1])`.
88
+
89
+
## Packaging a Custom Parser
90
+
91
+
To publish your custom parser to npm, perform the following:
92
+
93
+
1. Create a custom parser following the [Creating a Custom Parser](#creating-a-custom-parser) section above.
94
+
1.[Create an npm package](https://docs.npmjs.com/creating-node-js-modules) for the custom parser.
95
+
1. In your `package.json` file, set the [`main`](https://docs.npmjs.com/cli/v9/configuring-npm/package-json#main) field as the file that exports your custom parser.
96
+
1.[Publish the npm package.](https://docs.npmjs.com/creating-and-publishing-unscoped-public-packages)
97
+
98
+
For more information on publishing an npm package, refer to the [npm documentation](https://docs.npmjs.com/).
99
+
100
+
Once you've published the npm package, you can use it by adding the package to your project. For example:
101
+
102
+
```shell
103
+
npm install eslint-parser-myparser --save-dev
104
+
```
105
+
106
+
Then add the custom parser to your ESLint configuration file with the `parser` property. For example:
107
+
108
+
```js
109
+
// .eslintrc.js
110
+
111
+
module.exports= {
112
+
parser:'eslint-parser-myparser',
113
+
// ... rest of configuration
114
+
};
115
+
```
116
+
117
+
To learn more about using ESLint parsers in your project, refer to [Configure a Parser](../use/configure/parser).
118
+
119
+
## Example
120
+
121
+
For a complex example of a custom parser, refer to the [`@typescript-eslint/parser`](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/parser) source code.
122
+
123
+
A simple custom parser that provides a `context.parserServices.foo()` method to rules.
124
+
125
+
```javascript
126
+
// awesome-custom-parser.js
127
+
var espree =require("espree");
128
+
functionparseForESLint(code, options) {
129
+
return {
130
+
ast:espree.parse(code, options),
131
+
services: {
132
+
foo:function() {
133
+
console.log("foo");
134
+
}
135
+
},
136
+
scopeManager:null,
137
+
visitorKeys:null
138
+
};
139
+
};
140
+
141
+
module.exports= { parseForESLint };
142
+
```
143
+
144
+
Include the custom parser in an ESLint configuration file:
0 commit comments