groovysh - the Groovy repl-like shell

When a complete expression is found, it is compiled and evaluated. The result of the evaluation is stored into the _ variable.

Multi-line/complex expressions (like closure or class definitions) may be defined over several lines. When the shell detects that it has a complete expression it will compile and evaluate it.

You can define all the normal types, e.g. a class:

And use it in the normal way.

Defined classes are known to the shell and can be used in completion:

Shell variables are all untyped (i.e. no def or other type information).

This will set a shell variable:

But, this will evaluate a local variable and will not be saved to the shell’s environment:

This behavior can be changed by activating interpreter mode.

Variables definitions having the same name as existing definitions will replace the old definition with the new one.

Methods can be defined in the shell, and will be saved for later use.

Defining a method is easy:

And then using it is as one might expect:

If a method definition has the same signature as an existing definition, the old definition will be replaced with the new one.

When in interpreterMode, methods are remembered and given as extra statements when executing the next input.

When not in interpreterMode, the shell internally creates a closure to encapsulate the method and stores it in the shared variables. In this case, variables and methods share the same namespace.

If an exception is thrown, the shell will print the exception message and set a special exception shared variable.

Create an alias for a commandline fragment. The fragment could be Groovy code or a shell command. When evaluating a commandline, the alias will be replaced with the fragment:

The /cat command is already available. As can be seen here, aliases are replaced before command selection, so with the above alias in place, we actually invoke /less -F command, which has syntax highlighting, instead of the builtin /cat which doesn’t.

The fragment is expected to be at the start of a line but other text may follow:

Aliases are persisted in a .groovysh/aliases.json file in the user home directory.

See also the /unalias command, which allows aliases to be removed.

Concatenate and print files:

See also the /less command, which can be used to display the contents of a file a page at a time with syntax highlighting.

Change the current working directory. groovysh keeps track of a current working directory. You can view it with /pwd and change it with /cd.

The groovysh file commands (/cat, /less, /head, /slurp, /load, /ls, etc.) will use the current working directory.

There is a predefined shared variable PWD which can assist with invoking shell commands. So, on unix platforms, /ls will list the same files as /!ls $PWD.

See also the /pwd command, which prints the current working directory.

Display and manage the Groovy classloader data.

Let’s /grab a dependency, define a class using it, and then use the /classloader command to see the classloader data:

Clears the screen.

Displays the available colors.

This can be useful when configuring the console options, for example the PRNT_COLORS:

As this example shows, you can mix color names (like black and magenta), theme colors (like NUMBER), and color numbers (like 75).

Here is an example for HELP_COLORS:

Here is an example for LS_COLORS:

See the REPL Console Customization documentation for more details about such customization.

Displays the current buffer in the GroovyConsole.

Groovy has numerous classes for working with dates and time.

Here are some examples using the legacy date/calendar classes:

Here are some examples using the java.time classes:

The /date command is an alternative for those familiar with the unix date commandL:

Deletes objects from the shell. The command looks for any variable, method, type, shared data, or import with the given name and deletes it.

Here we create two variables, x and y, then delete the x variable:

See also, the /vars, /methods, /types, and /imports commands. These offer a -d|--delete option to delete the respective objects with completion.

Open documentation in a browser.

Documentation can be found for Groovy classes like this:

For Java classes, the /doc command will look for the class in the JDK documentation as well as in the groovy-jdk if Groovy has any extensions for that class:

Documentation is also extensible, so you can add your own documentation using regex patterns. For example, if you add the following line to your ~/.groovy/groovysh_init.groovy file:

Then, the following commands will open the Groovy documentation page and the JLine documentation for Terminal respectively in your browser:

The /echo command outputs its arguments to the console. Arguments are output verbatim, but variable expansion is also supported.

See also the /prnt command, which is similar but may perform additional formatting on the output(s).

Exit the shell.

This is the only way to exit the shell. Well, you can still CTRL-Z on unix platforms, but things like CTRL_C are trapped. (See JLine3 documentation for more details.)

Grab a dependency (Maven, Ivy, etc.) from Internet sources or cache, and add it to the Groovy Shell environment.

Completion is available. Currently, completion options are populated by known artifacts in the local Maven (~/.m2) and Grape (~/.groovy/grapes) repositories. In the future, completion from a remote repositories may be supported.

This command can be given at any time to add new dependencies.

The /grep command searches for patterns in files or standard input.

The /head command displays the start of a file.

Display, manage and recall edit-line history. The /history command has numerous options which let you list (with various options), save, read, and clear the edit-line history.

Here is an example of using the /history command:

Add a custom import which will be included for all shell evaluations.

This command can be given at any time to add new imports.

Completion is available and prompts a level at a time using the package structure of all known classes.

Once an import statement has been executed, relevant classes will become available for completion:

You can use this to list and delete existing imports.

Display or browse object info on the terminal or object browser.

Using the --gui/-g option displays the object in Groovy’s object browser:

Display the contents of a file (usually a page at a time). Formatting of common file types is supported.

If no filename is given, the contents of the current buffer are displayed.

Load a file into the buffer.

If no filename is given as an argument, the current shared variables are loaded from the .groovy/groovysh.ser file in the user home directory.

The /ls command lists files.

Wildcard support is available, so you can use /ls *.groovy to list all Groovy files in the current directory. File patterns which involve asterisks as well as slashes can sometimes be confused with Groovy’s comment syntax, so quote the pattern if in doubt:

Edit files or the current buffer.

The /nano command has numerous options:

You can use the /nano command to edit files or the current buffer:

If editing the current buffer, when you exit and then save, the buffer will be reloaded with the edited contents.

The /pipe command lets you create and delete custom pipe operators.

There are several builtin pipe and pipe-like operators:

For the pipe and and or operators, succeeds means executing without throwing an exception and returning a non-null, non-empty, non-zero result, i.e. true according to Groovy truth.

Here are some examples for and and or:

Pipe operators are handled by the shell. The left and right hand sides will be either repl commands or code passed to the Groovy engine for execution.

The pipe flip operator is most commonly used with commands:

It is less common, but it can also be used with code:

You can also define your own custom pipe operators, defined using /pipe [OPERATOR] [PREFIX] [POSTFIX], as these examples show:

JLine functionality includes support for named pipes and pipe aliases.

Here is a named pipe for finding fruit with small names:

Here is a pipe alias:

The pipe alias always has the pipe it is aliasing at the start, |. in the above example.

As a final example, let’s use a custom pipe with the output redirection operators to find fruit with large names:

The /prnt command outputs its argument to the console. Both variable expansion and formatting are supported.

See also the /echo command, which is similar but takes multiple arguments. It also supports variable expansion but doesn’t support formatting.

The /pwd command prints the current working directory.

Clears the current buffer and shared variables.

Saves the buffer’s contents to a file.

If no filename is given as an argument, the current shared variables are saved into the .groovy/groovysh.ser file in the user home directory.

Set options.

If no option is given, the current set options are displayed.

See also /unsetopt to unset options.

Set linereader variable values.

Show the shared variables (the binding). These include your shared variables as well as a few used for configuring various shell features.

Slurp files to shared variables. Groovy has a bunch of slurpers for various formats like XML, JSON, YAML, etc. You can use those in your code if you like, but the /slurp command can be a convenience shortcut. It supports most of the common formats, including JSON, XML, YAML, CSV, TOML and property files.

As you can see in the usage information at the end of the above image, you can also provide an encoding and a format. If no format is given, UTF_8 is the default. If no format is given, the shell will try to determine the format from the extension of the file (if given).

Although the details of the exact object returned are an implementation detail which may change in the future, the current behavior is as follows:

If these do change in the future, the replacement will be a compatible implementation, that follows the normal GPath conventions.

If you want more advanced control over the slurping, you can use Groovy’s "Slurper" classes directly, e.g. new XmlSlurper().parseText(…​).

The /sort command sorts files or standard input.

The /tail command displays the end of a file.

Show the declared types (enums, interfaces, classes, traits, annotation definitions, and records).

Types can be deleted using /types -d (completion is available) but see also the /del command:

Display information about threads.

Various options are available:

Unset options.

If no option is given, the current unset options are displayed.

See also /setopt to set options.

The /wc command displays word, line, character, and byte counts.

Allows aliases to be removed.

Removed aliases will also be removed from persistent storage.

History is stored in the file $HOME/.groovy/groovysh_history.

The style of coding you use in a REPL is slightly different from what you might use in a script. The style you use may also depend on whether you are using the Groovy Shell in interpreter mode or not.

The Groovy Shell attempts to blend a Groovy programming environment with a shell-like scripting environment. Sometimes the two are at odds. As one example, don’t try /ls /tmp/.txt. The / will be interpreted as the start of a comment. Instead, quote the argument like this /ls '/tmp/*.txt'.

The Groovy Shell relies heavily on the JLine3 library for its platform support. If you have specific platform problems, please refer to the JLine documentation.