NAME¶

jshell - interactively evaluate declarations, statements, and expressions of the Java programming language in a read-eval-print loop (REPL)

SYNOPSIS¶

jshell [options] [load-files]

options

Command-line options, separated by spaces. See Options for jshell.

load-files

One or more scripts to run when the tool is started. Scripts can contain any valid code snippets or JShell commands.

DESCRIPTION¶

JShell provides a way to interactively evaluate declarations, statements, and expressions of the Java programming language, making it easier to learn the language, explore unfamiliar code and APIs, and prototype complex code. Java statements, variable definitions, method definitions, class definitions, import statements, and expressions are accepted. The bits of code entered are called snippets.

As snippets are entered, they're evaluated, and feedback is provided. Feedback varies from the results and explanations of actions to nothing, depending on the snippet entered and the feedback mode chosen. Errors are described regardless of the feedback mode. Start with the verbose mode to get the most feedback while learning the tool.

Command-line options are available for configuring the initial environment when JShell is started. Within JShell, commands are available for modifying the environment as needed.

Existing snippets can be loaded from a file to initialize a JShell session, or at any time within a session. Snippets can be modified within the session to try out different variations and make corrections. To keep snippets for later use, save them to a file.

OPTIONS FOR JSHELL¶

--add-exports module/package

Specifies a package to be considered as exported from its defining module.

--add-modules module[,module...]

Specifies the root modules to resolve in addition to the initial module.

-Cflag

Provides a flag to pass to the compiler. To pass more than one flag, provide an instance of this option for each flag or flag argument needed.

--class-path path

Specifies the directories and archives that are searched to locate class files. This option overrides the path in the CLASSPATH environment variable. If the environment variable isn't set and this option isn't used, then the current directory is searched. For Linux and macOS, use a colon (:) to separate items in the path. For Windows, use a semicolon (;) to separate items.

--enable-preview

Allows code to depend on the preview features of this release.

--execution specification

Specifies an alternate execution engine, where specification is an ExecutionControl spec. See the documentation of the package jdk.jshell.spi for the syntax of the spec.

--feedback mode

Sets the initial level of feedback provided in response to what's entered. The initial level can be overridden within a session by using the /set feedback mode command. The default is normal.

--help or -h or -?

Prints a summary of standard options and exits the tool.

--help-extra or -X

Prints a summary of nonstandard options and exits the tool. Nonstandard options are subject to change without notice.

-Jflag

Provides a flag to pass to the runtime system. To pass more than one flag, provide an instance of this option for each flag or flag argument needed.

--module-path modulepath

Specifies where to find application modules. For Linux and macOS, use a colon (:) to separate items in the path. For Windows, use a semicolon (;) to separate items.

--no-startup

Prevents startup scripts from running when JShell starts. Use this option to run only the scripts entered on the command line when JShell is started, or to start JShell without any preloaded information if no scripts are entered. This option can't be used if the --startup option is used.

-q

Sets the feedback mode to concise, which is the same as entering --feedback concise.

-Rflag

Provides a flag to pass to the remote runtime system. To pass more than one flag, provide an instance of this option for each flag or flag argument to pass.

-s

Sets the feedback mode to silent, which is the same as entering --feedback silent.

--show-version

Prints version information and enters the tool.

--startup file

Overrides the default startup script for this session. The script can contain any valid code snippets or commands.

-v

Sets the feedback mode to verbose, which is the same as entering --feedback verbose.

--version

Prints version information and exits the tool.

JSHELL COMMANDS¶

Within the jshell tool, commands are used to modify the environment and manage code snippets.

/drop {name|id|startID-endID} [{name|id|startID-endID}...]

Drops snippets identified by name, ID, or ID range, making them inactive. For a range of IDs, provide the starting ID and ending ID separated with a hyphen. To provide a list, separate the items in the list with a space. Use the /list command to see the IDs of code snippets.

/edit [option]

Opens an editor. If no option is entered, then the editor opens with the active snippets.

/env [options]

Displays the environment settings, or updates the environment settings and restarts the session. If no option is entered, then the current environment settings are displayed. If one or more options are entered, then the session is restarted as follows:

/exit [integer-expression-snippet]

Exits the tool. If no snippet is entered, the exit status is zero. If a snippet is entered and the result of the snippet is an integer, the result is used as the exit status. If an error occurs, or the result of the snippet is not an integer, an error is displayed and the tool remains active.

/history

Displays what was entered in this session.

/help [command|subject]

Displays information about commands and subjects. If no options are entered, then a summary of information for all commands and a list of available subjects are displayed. If a valid command is provided, then expanded information for that command is displayed. If a valid subject is entered, then information about that subject is displayed.

/imports

Displays the current active imports, including those from the startup scripts and scripts that were entered on the command line when JShell was started.

/list [option]

Displays a list of snippets and their IDs. If no option is entered, then all active snippets are displayed, but startup snippets aren't.

/methods [option]

Displays information about the methods that were entered. If no option is entered, then the name, parameter types, and return type of all active methods are displayed.

/open file

Opens the script specified and reads the snippets into the tool. The script can be a local file or one of the following predefined scripts:

/reload [options]

Restarts the session as follows:

/reset [options]

Discards all entered snippets and restarts the session as follows:

/save [options] file

Saves snippets and commands to the file specified. If no options are entered, then active snippets are saved.

/set [setting]

Sets configuration information, including the external editor, startup settings, and feedback mode. This command is also used to create a custom feedback mode with customized prompt, format, and truncation values. If no setting is entered, then the current setting for the editor, startup settings, and feedback mode are displayed.

/types [option]

Displays classes, interfaces, and enums that were entered. If no option is entered, then all current active classes, interfaces, and enums are displayed.

/vars [option]

Displays the name, type, and value of variables that were entered. If no option is entered, then all current active variables are displayed.

/?

Same as the /help command.

/!

Reruns the last snippet.

/{name|id|startID-endID} [{name|id|startID-endID}...]

Reruns the snippets identified by ID, range of IDs, or name. For a range of IDs, provide the starting ID and ending ID separated with a hyphen. To provide a list, separate the items in the list with a space. The first item in the list must be an ID or ID range. Use the /list command to see the IDs of the code snippets.

/-n

Reruns the -nth previous snippet. For example, if 15 code snippets were entered, then /-4 runs the 11th snippet. Commands aren't included in the count.

INPUT SHORTCUTS¶

The following shortcuts are available for entering commands and snippets in JShell.

INPUT EDITING¶

The editing capabilities of JShell are similar to that of other common shells. Keyboard keys and key combinations provide line editing shortcuts. The Ctrl key and Meta key are used in key combinations. If your keyboard doesn't have a Meta key, then the Alt key is often mapped to provide Meta key functionality.

Line Editing Shortcuts

EXAMPLE OF STARTING AND STOPPING A JSHELL SESSION¶

JShell is provided with the JDK. To start a session, enter jshell on the command line. A welcome message is printed, and a prompt for entering commands and snippets is provided.

% jshell
|  Welcome to JShell -- Version 9
|  For an introduction type: /help intro
jshell>

To see which snippets were automatically loaded when JShell started, use the /list -start command. The default startup snippets are import statements for common packages. The ID for each snippet begins with the letter s, which indicates it's a startup snippet.

jshell> /list -start


  s1 : import java.io.*;


  s2 : import java.math.*;


  s3 : import java.net.*;


  s4 : import java.nio.file.*;


  s5 : import java.util.*;


  s6 : import java.util.concurrent.*;


  s7 : import java.util.function.*;


  s8 : import java.util.prefs.*;


  s9 : import java.util.regex.*;


 s10 : import java.util.stream.*;
jshell>

To end the session, use the /exit command.

jshell> /exit
|  Goodbye
%

EXAMPLE OF ENTERING SNIPPETS¶

Snippets are Java statements, variable definitions, method definitions, class definitions, import statements, and expressions. Terminating semicolons are automatically added to the end of a completed snippet if they're missing.

The following example shows two variables and a method being defined, and the method being run. Note that a scratch variable is automatically created to hold the result because no variable was provided.

jshell> int a=4
a ==> 4
jshell> int b=8
b ==> 8
jshell> int square(int i1) {


   ...> return i1 * i1;


   ...> }
|  created method square(int)
jshell> square(b)
$5 ==> 64

EXAMPLE OF CHANGING SNIPPETS¶

Change the definition of a variable, method, or class by entering it again.

The following examples shows a method being defined and the method run:

jshell> String grade(int testScore) {


   ...>     if (testScore >= 90) {


   ...>         return "Pass";


   ...>     }


   ...>     return "Fail";


   ...> }
|  created method grade(int)
jshell> grade(88)
$3 ==> "Fail"

To change the method grade to allow more students to pass, enter the method definition again and change the pass score to 80. Use the up arrow key to retrieve the previous entries to avoid having to reenter them and make the change in the if statement. The following example shows the new definition and reruns the method to show the new result:

jshell> String grade(int testScore) {


   ...>     if (testScore >= 80) {


   ...>         return "Pass";


   ...>     }


   ...>     return "Fail";


   ...> }
|  modified method grade(int)
jshell> grade(88)
$5 ==> "Pass"

For snippets that are more than a few lines long, or to make more than a few changes, use the /edit command to open the snippet in an editor. After the changes are complete, close the edit window to return control to the JShell session. The following example shows the command and the feedback provided when the edit window is closed. The /list command is used to show that the pass score was changed to 85.

jshell> /edit grade
|  modified method grade(int)
jshell> /list grade


   6 : String grade(int testScore) {


           if (testScore >= 85) {


               return "Pass";


           }


           return "Fail";


       }

EXAMPLE OF CREATING A CUSTOM FEEDBACK MODE¶

The feedback mode determines the prompt that's displayed, the feedback messages that are provided as snippets are entered, and the maximum length of a displayed value. Predefined feedback modes are provided. Commands for creating custom feedback modes are also provided.

Use the /set mode command to create a new feedback mode. In the following example, the new mode mymode, is based on the predefined feedback mode, normal, and verifying command feedback is displayed:

jshell> /set mode mymode normal -command
|  Created new feedback mode: mymode

Because the new mode is based on the normal mode, the prompts are the same. The following example shows how to see what prompts are used and then changes the prompts to custom strings. The first string represents the standard JShell prompt. The second string represents the prompt for additional lines in multiline snippets.

jshell> /set prompt mymode
|  /set prompt mymode "\njshell> " "   ...> "
jshell> /set prompt mymode "\nprompt$ " "   continue$ "

The maximum length of a displayed value is controlled by the truncation setting. Different types of values can have different lengths. The following example sets an overall truncation value of 72, and a truncation value of 500 for variable value expressions:

jshell> /set truncation mymode 72
jshell> /set truncation mymode 500 varvalue

The feedback displayed after snippets are entered is controlled by the format setting and is based on the type of snippet entered and the action taken for that snippet. In the predefined mode normal, the string created is displayed when a method is created. The following example shows how to change that string to defined:

jshell> /set format mymode action "defined" added-primary

Use the /set feedback command to start using the feedback mode that was just created. The following example shows the custom mode in use:

jshell> /set feedback mymode
|  Feedback mode: mymode
prompt$ int square (int num1){


   continue$ return num1*num1;


   continue$ }
|  defined method square(int)
prompt$