JEP 236: Parser API for Nashorn
|Component||core-libs / jdk.nashorn|
|Discussion||nashorn dash dev at openjdk dot java dot net|
|Reviewed by||Jim Laskey|
|Endorsed by||Brian Goetz, Jim Laskey|
Define a supported API for Nashorn's ECMAScript abstract syntax tree.
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.
The AST nodes will represent notions in the ECMAScript specification insofar as possible, but they will not be exactly the same. Wherever possible the
javactree 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.
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
jdk.nashorn.api.tree. A similar abstract syntax-tree
API is already supported by
javac, in the
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.
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 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.
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
ErrorTree nodes as needed.