Package jdk.jshell

Provides interfaces for creating tools, such as a Read-Eval-Print Loop (REPL),
which interactively evaluate "snippets" of Java programming language code.
Where a "snippet" is a single expression, statement, or declaration.
This functionality can be used to enhance tools such as IDEs or can be
stand-alone.

JShell is the central class. An instance of
JShell holds the evaluation state, which is both the current
set of source snippets and the execution state they have produced.

Each source snippet is represented by an instance of a subclass of
Snippet. For example, a statement is represented by an
instance of StatementSnippet, and a method declaration is
represented by an instance of MethodSnippet.
Snippets are created when
JShell.eval(String)
is invoked with an input which includes one or more snippets of code.

Any change to the compilation status of a snippet is reported with a
SnippetEvent. There are three major kinds of
changes to the status of a snippet: it can created with eval,
it can be dropped from the active source state with
JShell.drop(jdk.jshell.Snippet), and it can have
its status updated as a result of a status change in another snippet.
For
example: given js, an instance of JShell, executing
js.eval("int x = 5;") will add the variable x to
the source state and will generate an event describing the creation of a
VarSnippet for x. Then executing
js.eval("int timesx(int val) { return val * x; }") will add
a method to the source state and will generate an event
describing the creation of a MethodSnippet for
timesx.
Assume that varx holds the snippet created by the first
call to eval, executing js.drop(varx) will
generate two events: one for changing the status of the
variable snippet to DROPPED and one for
updating the method snippet (which now has an unresolved reference to
x).

Of course, for any general application of the API, the input would not be
fixed strings, but would come from the user. Below is a very simplified
example of how the API might be used to implement a REPL.

To register for status change events use
JShell.onSnippetEvent(java.util.function.Consumer).
These events are only generated by eval and drop,
the return values of these methods are the list of events generated by that
call. So, as in the example above, events can be used without registering
to receive events.

If you experiment with this example, you will see that failing to terminate
a statement or variable declaration with a semi-colon will simply fail.
An unfinished entry (for example a desired multi-line method) will also just
fail after one line. The utilities in SourceCodeAnalysis
provide source boundary and completeness analysis to address cases like
those. SourceCodeAnalysis also provides suggested completions
of input, as might be used in tab-completion.