JEP 236: Parser API for Nashorn

Authorsundararajan.athijegannathan@oracle.com
OwnerSundararajan Athijegannathan
Created2014/06/26 08:42
Updated2017/01/27 22:42
TypeFeature
StatusCompleted
Componentcore-libs / jdk.nashorn
ScopeJDK
Discussionnashorn dash dev at openjdk dot java dot net
EffortM
DurationM
Priority3
Reviewed byJim Laskey
Endorsed byBrian Goetz, Jim Laskey
Release9
Issue8048176

Summary

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

Goals

Non-Goals

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.