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.

This page pertains to the new groovysh which at the moment needs to be explicitly enabled by setting the NEWSHELL environment variable to any value (unset or empty will invoke the previous groovysh implementation). NEWSHELL=true ./bin/groovysh

Features

• No need for go command to execute buffer.
• Rich cross-platform edit-line editing, history and completion thanks to JLine.
• ANSI colors (prompt, exception traces, etc).
• Simple, yet robust, command system with online help, user alias support and more.
• User profile support

Command-line Options and Arguments

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

./bin/groovysh --help
usage: groovysh [options] [...]
  -C, --color[=FLAG]         Enable or disable use of ANSI colors
  -D, --define=NAME=VALUE    Define a system property
  -T, --terminal=TYPE        Specify the terminal TYPE to use
  -V, --version              Display the version
  -d, --debug                Enable debug output
  -h, --help                 Display this help message
  -q, --quiet                Suppress superfluous output
  -v, --verbose              Enable verbose output

In addition to options, commands or expressions can be given on the command-line which will invoke the shell in non-interactive mode. The commands or expressions will be evaluated and the shell will exit. If no additional arguments are given the shell will startup interactively.

Execute a Command

./bin/groovysh 'show preferences'
No preferences are set

Evaluate an Expression

./bin/groovysh 'System.properties.each { k, v -> println("$k = $v") }'
java.runtime.name = Java(TM) 2 Runtime Environment, Standard Edition
sun.boot.library.path = /System/Library/Frameworks/JavaVM.framework/Versions/1.5.0/Libraries
java.vm.version = 1.5.0_07-87
awt.nativeDoubleBuffering = true
gopherProxySet = false
...

Evaluating Expressions

Simple Expressions

println "Hello"

Evaluation Result

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

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()

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.

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.codehaus.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
  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 buffers
  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

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.

import

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

display

Display the contents of the current buffer.

clear

Clear the current buffer.

show

Show variables, classes or preferences or imports.

inspect

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

purge

Purges objects from the shell.

edit

Edit the current buffer.

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.

history

Display, manage and recall edit-line history.

alias

Create an alias.

set

Set or list preferences.

Preferences

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

Recognized Preferences

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.

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.

Setting a Preference

set verbosity DEBUG

Listing Preferences

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

show preferences

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

Clearing Preferences (ie. Resetting to Defaults)

purge preferences

User Profile Scripts and State

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.

State

$HOME/.groovy/groovysh.history

Edit-line history is stored in this file.

Screen Shots

These shots have been taken over the development of the new shell, so some of the content might look slightly different. Also, note the yellow colors here are the shell's bold color, so the colors might look different depending on how the enclosing shell has its colors setup.