Summary

Add a new method to the source code analysis arm of the JShell API to retrieve Snippet information without influencing state.

Problem

Currently the only way to get snippet information is with eval(), which makes user visible changes to the state including: the compilation state, the execution state, and the set of Snippets. Tools need snippet information to make choices about user interaction. The driving bug for this enhancement is JDK-8166334, which is new functionality in the jshell tool to convert expressions/statements to methods -- it needs to know it the snippet is valid, if it of the correct kind, and what its type is -- all of which are available from the Snippet. This is one example of a general need.

Solution

The JShell API has a SourceCodeAnalysis arm -- this functionality is added to that arm. The new sourceToSnippets(String) method does the same conversion to Snippet as is done in JShell.eval(String) without installing it as an active Snippet, declaring named entities, or evaluating the code.

One alternative would be to call Compiler API functionality, but this would be a significant step away from ease of use. Another alternative would be to use 'JShell.eval(String)` and try to undo or hide the state changes -- the snippets could be filtered from user view but the changes to compilation, declaration, and evaluation state would be extremely hard to undo.

Specification

The JShell API, specdiff, and webrev are attached.

The only API change is the addition of this method --

http://cr.openjdk.java.net/~rfield/8182270v2.api/jdk/jshell/SourceCodeAnalysis.html#sourceToSnippets-java.lang.String-

sourceToSnippets

public abstract List<Snippet> sourceToSnippets​(String input)

Converts the source code of a snippet into a Snippet object (or list of Snippet objects in the case of
some var declarations, e.g.: int x, y, z;). Does not install the snippets: declarations are not
accessible by other snippets; imports are not added. Does not execute the snippets.

Queries may be done on the Snippet object. The Snippet.id() will be "*UNASSOCIATED*". The
returned snippets are not associated with the JShell instance, so attempts to pass them to JShell
methods will throw an IllegalArgumentException. They will not appear in queries for snippets -- for
example, JShell.snippets().

Restrictions on the input are as in JShell.eval.

Only preliminary compilation is performed, sufficient to build the Snippet. Snippets known to be
erroneous, are returned as ErroneousSnippet, other snippets may or may not be in error.

Parameters:
    input - The input String to convert
Returns:
    usually a singleton list of Snippet, but may be empty or multiple
Throws:
    IllegalStateException - if the JShell instance is closed.

Specdiff for which is here:

http://cr.openjdk.java.net/~rfield/8182270v2.specdiff/SourceCodeAnalysis.html

Full specdiff:

http://cr.openjdk.java.net/~rfield/8182270v2.specdiff/overview-summary.html

JShell API:

http://cr.openjdk.java.net/~rfield/8182270v2.jshell/

Full API:

http://cr.openjdk.java.net/~rfield/8182270v2.api/jdk/

Webrev:

http://cr.openjdk.java.net/~rfield/8182270v2.webrev/