JEP 236: Parser API for Nashorn

Summary

Define a supported API for Nashorn's ECMAScript abstract syntax tree.

Goals

• Provide interface classes to represent Nashorn syntax-tree nodes.

• Provide a factory to create a configured parser instance, with configuration done by passing Nashorn command-line options via an API.

• Provide a visitor-pattern API to visit AST nodes.

• Provide sample/test programs to use the API.

Non-Goals

• The AST nodes will represent notions in the ECMAScript specification insofar as possible, but they will not be exactly the same. Wherever possible the javac tree API's interfaces will be adopted for ECMAScript.

• No external parser/tree standard or API will be used.

• There will be no script-level parser API. This is a Java API, although scripts can call into Java and therefore make use of this API.

Motivation

IDEs such as NetBeans use Nashorn for ECMAScript editing/debugging as well as ECMAScript code analysis. These tools and frameworks presently use Nashorn's internal AST representation for code analysis. This usage of internal classes in the jdk.nashorn.internal.ir package and its sub-packages prevent free evolution of the internal implementation classes of Nashorn. This JEP will define a Nashorn parser API in an exposed package, jdk.nashorn.api.tree. A similar abstract syntax-tree API is already supported by javac, in the com.sun.source package and its subpackages.

The parser API will enable ECMAScript code analysis by programs such as IDEs and server-side frameworks without those programs having to depend on Nashorn's internal implementation classes.

Description

The attached javadoc file contains documentation of the proposed interfaces and classes of the new jdk.nashorn.api.tree package. The starting point of the API is the ParserFactory and ParserFactoryImpl classes. A ParserFactory object accepts an array of strings which are options to configure the parser. The options supported are the same as the options supported by the Nashorn shell tool jjs, as well as the nashorn.args system property of the Nashorn script engine.

Once a parser instance is created then ECMAScript source from a string, URL, or file can be submitted to the parser, which will return a CompilationUnitTree object. Any parsing errors are reported via the DiagnosticListener object supplied by the caller.

Testing

There are already over 1,000 Nashorn script tests. All parsable sources will be parsed to check that the parser does not crash. Selected files containing various code patterns will be parsed, and their JSON representation will be compared against expected outcomes. Also, a set of files with parse errors will be added to check that the user-provided DiagnosticListener receives error messages and the resulting CompilationUnitTree has ErrorTree nodes as needed.