# Groovysh, the Groovy shell

version 5.0.0-alpha-7

## 1. Groovy : Groovy Shell

The Groovy Shell, aka. `groovysh` is a command-line application which allows easy access to evaluate Groovy expressions, define classes and run simple experiments.

### 1.1. Features

- No need for `go` command to execute buffer.

- Rich cross-platform edit-line editing, history and completion thanks to JLine2.

- ANSI colors (prompt, exception traces, etc).

- Simple, yet robust, command system with online help, user alias support and more.

- User profile support

### 1.2. Command-line Options and Arguments

The shell supports several options to control verbosity, ANSI coloring and other features.

    ./bin/groovysh --help

    Usage: groovysh [options] [...]
    The Groovy Shell, aka groovysh, is a command-line application which allows easy
    access to evaluate Groovy expressions, define classes and run simple
    experiments.
      -C, --color[=<FLAG>]    Enable or disable use of ANSI colors
          -cp, -classpath, --classpath
                              Specify where to find the class files - must be first
                                argument
      -d, --debug             Enable debug output
      -D, --define=<name=value>
                              Define a system property
      -e, --evaluate=<CODE>   Evaluate the code first when starting interactive session
      -h, --help              Display this help message
      -pa, --parameters       Generate metadata for reflection on method parameter names
                                (jdk8+ only)
      -pr, --enable-preview   Enable preview Java features (jdk12+ only)
      -q, --quiet             Suppress superfluous output
      -T, --terminal=<TYPE>   Specify the terminal TYPE to use
      -v, --verbose           Enable verbose output
      -V, --version           Display the version

### 1.3. Evaluating Expressions

#### 1.3.1. Simple Expressions

    println "Hello"

#### 1.3.2. Evaluation Result

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

#### 1.3.3. Multi-line Expressions

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.

##### Define a Class

    class Foo {
        def bar() {
            println "baz"
        }
    }

##### Use the Class

    foo = new Foo()
    foo.bar()

#### 1.3.4. Variables

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

This will set a shell variable:

    foo = "bar"

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

    def foo = "bar"

This behavior can be changed by activating interpreter mode.

#### 1.3.5. Functions

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

Defining a function is easy:

    groovy:000> def hello(name) {
    groovy:001> println("Hello $name")
    groovy:002> }

And then using it is as one might expect:

    hello("Jason")

Internally the shell creates a closure to encapsulate the function and then binds the closure to a variable. So variables and functions share the same namespace.

### 1.4. Commands

The shell has a number of different commands, which provide rich access to the shell’s environment.

Commands all have a name and a shortcut (which is something like `\h`). Commands may also have some predefined system aliases. Users may also create their own aliases.

#### 1.4.1. Recognized Commands

##### `help`

Display the list of commands (and aliases) or the help text for specific command.

The Command List

    groovy:000> :help

    For information about Groovy, visit:
        http://groovy-lang.org

    Available commands:
      :help      (:h ) Display this help message
      ?          (:? ) Alias to: :help
      :exit      (:x ) Exit the shell
      :quit      (:q ) Alias to: :exit
      import     (:i ) Import a class into the namespace
      :display   (:d ) Display the current buffer
      :clear     (:c ) Clear the buffer and reset the prompt counter
      :show      (:S ) Show variables, classes or imports
      :inspect   (:n ) Inspect a variable or the last result with the GUI object browser
      :purge     (:p ) Purge variables, classes, imports or preferences
      :edit      (:e ) Edit the current buffer
      :load      (:l ) Load a file or URL into the buffer
      .          (:. ) Alias to: :load
      :save      (:s ) Save the current buffer to a file
      :record    (:r ) Record the current session to a file
      :history   (:H ) Display, manage and recall edit-line history
      :alias     (:a ) Create an alias
      :set       (:= ) Set (or list) preferences
      :grab      (:g ) Add a dependency to the shell environment
      :register  (:rc) Register a new command with the shell
      :doc       (:D ) Open a browser window displaying the doc for the argument

    For help on a specific command type:
        :help <command>

Help for a Command

While in the interactive shell, you can ask for help for any command to get more details about its syntax or function. Here is an example of what happens when you ask for help for the `help` command:

    groovy:000> :help :help

    usage: :help [<command>]

    Display the list of commands or the help text for <command>.

##### `exit`

Exit the shell.

This is the only way to exit the shell. Well, you can still `CTRL-C`, but the shell will complain about an abnormal shutdown of the JVM.

##### `import`

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

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

##### `grab`

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

    groovy:000> :grab 'com.google.guava:guava:19.0'
    groovy:000> import com.google.common.collect.BiMap
    ===> com.google.common.collect.BiMap

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

##### `display`

Display the contents of the current buffer.

This only displays the buffer of an incomplete expression. Once the expression is complete, the buffer is reset. The prompt will update to show the size of the current buffer as well.

Example

    groovy:000> class Foo {
    groovy:001> def bar
    groovy:002> def baz() {
    groovy:003> :display
     001> class Foo {
     002> def bar
     003> def baz() {

##### `clear`

Clears the current buffer, resetting the prompt counter to 000. Can be used to recover from compilation errors.

##### `show`

Show variables, classes or preferences or imports.

`show variables`

    groovy:000> :show variables
    Variables:
      _ = true

`show classes`

`show imports`

`show preferences`

`show all`

##### `inspect`

Opens the GUI object browser to inspect a variable or the result of the last evaluation.

##### `purge`

Purges objects from the shell.

`purge variables`

`purge classes`

`purge imports`

`purge preferences`

`purge all`

##### `edit`

Edit the current buffer in an external editor.

Currently only works on UNIX systems which have the `EDITOR` environment variable set, or have configured the `editor` preference.

##### `load`

Load one or more files (or urls) into the buffer.

##### `save`

Saves the buffer’s contents to a file.

##### `record`

Record the current session to a file.

`record start`

`record stop`

`record status`

##### `history`

Display, manage and recall edit-line history.

`history show`

`history recall`

`history flush`

`history clear`

##### `alias`

Create an alias.

##### `doc`

Opens a browser with documentation for the provided class.

For example, we can get both the Javadoc and GDK enhancements doc for `java.util.List` (shown running on JDK17):

    groovy:000> :doc java.util.List
    https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/List.html
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/groovy-jdk/java/util/List.html

This will print the documentation URLs found and open two windows (or tabs, depending on your browser):

- one for the JDK documentation

- one for the GDK documentation

By default, for Java classes, the `java.base` module is assumed. You can specify an optional module for other cases (shown running on JDK17):

    groovy:000> :doc java.scripting javax.script.ScriptContext
    https://docs.oracle.com/en/java/javase/17/docs/api/java.scripting/javax/script/ScriptContext.html

For backwards compatibility, if no module is specified when searching for Java classes, and no class is found in the `java.base` module, an additional attempt is made to find documentation for the class in the JDK8 (pre-module) Javadoc:

    groovy:000> :doc javax.script.ScriptContext
    https://docs.oracle.com/javase/8/docs/api/javax/script/ScriptContext.html

To get the Groovydoc for `groovy.ant.AntBuilder` and `groovy.xml.XmlSlurper`:

    groovy:000> :doc groovy.ant.AntBuilder
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/gapi/groovy/ant/AntBuilder.html
    groovy:000> :doc groovy.xml.XmlSlurper
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/gapi/groovy/xml/XmlSlurper.html

To get both the Groovydoc and GDK enhancements doc for `groovy.lang.Closure` and `groovy.sql.GroovyResultSet`:

    groovy:000> :doc groovy.lang.Closure
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/gapi/groovy/lang/Closure.html
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/groovy-jdk/groovy/lang/Closure.html
    groovy:000> :doc groovy.sql.GroovyResultSet
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/gapi/groovy/sql/GroovyResultSet.html
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/groovy-jdk/groovy/sql/GroovyResultSet.html

Documentation is also available for the GDK enhancements to primitive arrays and arrays of arrays:

    groovy:000> :doc int[]
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/groovy-jdk/primitives-and-primitive-arrays/int%5B%5D.html
    groovy:000> :doc double[][]
    https://docs.groovy-lang.org/5.0.0-alpha-7/html/groovy-jdk/primitives-and-primitive-arrays/double%5B%5D%5B%5D.html

| In contexts where opening a browser may not be desirable, e.g. on a CI server, this command can be disabled by setting the `groovysh.disableDocCommand` system property to `true`.

##### `set`

Set or list preferences.

### 1.5. Preferences

Some aspects of `groovysh` behaviors can be customized by setting preferences. Preferences are set using the `set` command or the `:=` shortcut.

#### 1.5.1. Recognized Preferences

##### `interpreterMode`

Allows the use of typed variables (i.e. `def` or other type information):

    groovy:000> def x = 3
    ===> 3
    groovy:000> x
    ===> 3

It’s especially useful for copy&pasting code from tutorials etc. into the running session.

##### `verbosity`

Set the shell’s verbosity level. Expected to be one of:

- `DEBUG`

- `VERBOSE`

- `INFO`

- `QUIET`

Default is `INFO`.

If this preference is set to an invalid value, then the previous setting will be used, or if there is none, then the preference is removed and the default is used.

##### `colors`

Set the shell’s use of colors.

Default is `true`.

##### `show-last-result`

Show the last result after an execution.

Default is `true`.

##### `sanitize-stack-trace`

Sanitize (trim-down/filter) stack traces.

Default is `true`.

##### `editor`

Configures the editor used by the `edit` command.

Default is the value of the system environment variable `EDITOR`.

To use TextEdit, the default text editor on macOS, configure: set editor /Applications/TextEdit.app/Contents/MacOS/TextEdit

#### 1.5.2. Setting a Preference

    groovy:000> :set verbosity DEBUG

#### 1.5.3. Listing Preferences

To list the current set preferences (and their values):

    groovy:000> :show preferences

Limitation: At the moment, there is no way to list all the known/available preferences to be set.

#### 1.5.4. Clearing Preferences (i.e. Resetting to Defaults)

    groovy:000> :purge preferences

### 1.6. User Profile Scripts and State

#### 1.6.1. Profile Scripts

##### `$HOME/.groovy/groovysh.profile`

This script, if it exists, is loaded when the shell starts up.

##### `$HOME/.groovy/groovysh.rc`

This script, if it exists, is loaded when the shell enters interactive mode.

#### 1.6.2. State

##### `$HOME/.groovy/groovysh.history`

Edit-line history is stored in this file.

### 1.7. Custom commands

The `register` command allows you to register custom commands in the shell. For example, writing the following will register the `Stats` command:

    groovy:000> :register Stats

where the `Stats` class is a class extending the `org.apache.groovy.groovysh.CommandSupport` class. For example:

    import org.apache.groovy.groovysh.CommandSupport
    import org.apache.groovy.groovysh.Groovysh

    class Stats extends CommandSupport {
        protected Stats(final Groovysh shell) {
            super(shell, 'stats', 'T')
        }

        public Object execute(List args) {
            println "Free memory: ${Runtime.runtime.freeMemory()}"
        }

    }

Then the command can be called using:

    groovy:000> :stats
    stats
    Free memory: 139474880
    groovy:000>

Note that the command class must be found on classpath: you cannot define a new command from within the shell.

### 1.8. Troubleshooting

Please report any problems you run into. Please be sure to mark the JIRA issue with the `Groovysh` component.

#### 1.8.1. Platform Problems

##### Problems loading the JLine DLL

On Windows, JLine2 (which is used for the fancy shell input/history/completion fluff), uses a tiny DLL file to trick the evil Windows faux-shell (`CMD.EXE` or `COMMAND.COM`) into providing Java with unbuffered input. In some rare cases, this might fail to load or initialize.

One solution is to disable the frills and use the unsupported terminal instance. You can do that on the command-line using the `--terminal` flag and set it to one of:

- `none`

- `false`

- `off`

- `jline.UnsupportedTerminal`

    groovysh --terminal=none

##### Problems with Cygwin on Windows

Some people have issues when running groovysh with cygwin. If you have troubles, the following may help:

    stty -icanon min 1 -echo
    groovysh --terminal=unix
    stty icanon echo

## 2. GMavenPlus Maven Plugin

GMavenPlus is a Maven plugin with goals that support launching a Groovy Shell or Groovy Console bound to a Maven project.

## 3. Gradle Groovysh Plugin

Gradle Groovysh Plugin is a Gradle plugin that provides gradle tasks to start a Groovy Shell bound to a Gradle project.