New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Parser services are undocumented #8390

Closed
not-an-aardvark opened this Issue Apr 2, 2017 · 2 comments

Comments

Projects
None yet
2 participants
@not-an-aardvark
Member

not-an-aardvark commented Apr 2, 2017

The parseForESLint API from #6974 was added in #6975, but there isn't any documentation for this.

@VictorHom

This comment has been minimized.

Show comment
Hide comment
@VictorHom

VictorHom Jun 3, 2017

Member

@not-an-aardvark
For this issue, should it be a new .md file under docs/developer_guide or can it live in an existing file?

I've read through #6974 and #6975 (among other links in those threads and pr) and I don't have experience with this feature.

From what I understand, the parseForESLint capabilities are meant to work with services like https://github.com/eslint/typescript-eslint-parser . By default, the parser will parse with existing configurations. If you set up your eslint configurations with "parser": "my-custom-eslint-parser", then that means"my-custom-eslint-parser" is going to create your own AST for ESLint to work with. The custom ESLint parser should reveal a function "parseForESLint" which is what the ESLint linter will use to make the AST.

Question:
Does the custom parser have to use a certain type of javascript parser? I'm unfamiliar with the parsers. If you have any good resources for high level overview, I would greatly appreciate.

Member

VictorHom commented Jun 3, 2017

@not-an-aardvark
For this issue, should it be a new .md file under docs/developer_guide or can it live in an existing file?

I've read through #6974 and #6975 (among other links in those threads and pr) and I don't have experience with this feature.

From what I understand, the parseForESLint capabilities are meant to work with services like https://github.com/eslint/typescript-eslint-parser . By default, the parser will parse with existing configurations. If you set up your eslint configurations with "parser": "my-custom-eslint-parser", then that means"my-custom-eslint-parser" is going to create your own AST for ESLint to work with. The custom ESLint parser should reveal a function "parseForESLint" which is what the ESLint linter will use to make the AST.

Question:
Does the custom parser have to use a certain type of javascript parser? I'm unfamiliar with the parsers. If you have any good resources for high level overview, I would greatly appreciate.

@not-an-aardvark

This comment has been minimized.

Show comment
Hide comment
@not-an-aardvark

not-an-aardvark Jun 18, 2017

Member

Sorry about the delay -- I missed this notification and hadn't realized you replied.

Basically, a parser is a module which accepts some some source code text and returns an AST. By default, ESLint uses the espree parser to create an AST.

Parsers work by exposing a parse method. The parse method accepts the source code text as the first argument, and can optionally accept an object containing parse options as the second argument. The parse method returns an AST, which must conform to the ESTree specification. Beyond this spec, there aren't any requirements for how the parser is implemented. For example, a parser could theoretically ignore the source text and return an entirely unrelated AST. (Of course, a parser that did this would not be very useful.)

The motivation for #6974 was that it would be useful for parsers to be able to provide additional data or functionality, beyond just an AST. For example, it would be nice if the typescript parser could provide type-checking capabilities, but that wasn't possible with the parse method because it was required to just return the AST.

To allow this, we now use the parseForESLint method on a parser (and fall back to the parse method if parseForESLint isn't present). parseForESLint accepts the same arguments as parse, but instead of just returning an AST, it returns an object where the ast property is the AST. The object can also have a services property containing arbitrary parser-dependent services (e.g. type-checking methods). The value of the service property is available to rules as context.parserServices.

Member

not-an-aardvark commented Jun 18, 2017

Sorry about the delay -- I missed this notification and hadn't realized you replied.

Basically, a parser is a module which accepts some some source code text and returns an AST. By default, ESLint uses the espree parser to create an AST.

Parsers work by exposing a parse method. The parse method accepts the source code text as the first argument, and can optionally accept an object containing parse options as the second argument. The parse method returns an AST, which must conform to the ESTree specification. Beyond this spec, there aren't any requirements for how the parser is implemented. For example, a parser could theoretically ignore the source text and return an entirely unrelated AST. (Of course, a parser that did this would not be very useful.)

The motivation for #6974 was that it would be useful for parsers to be able to provide additional data or functionality, beyond just an AST. For example, it would be nice if the typescript parser could provide type-checking capabilities, but that wasn't possible with the parse method because it was required to just return the AST.

To allow this, we now use the parseForESLint method on a parser (and fall back to the parse method if parseForESLint isn't present). parseForESLint accepts the same arguments as parse, but instead of just returning an AST, it returns an object where the ast property is the AST. The object can also have a services property containing arbitrary parser-dependent services (e.g. type-checking methods). The value of the service property is available to rules as context.parserServices.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.