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.

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.

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.

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.

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 rest. The prompt will update to show the size of the current buffer as well.

Example

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.

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.

editor

Configures the editor used by the edit command.

Default is the value of the system environment variable EDITOR.

Mac OS X

Icon

To use TextEdit, the default text editor on Mac OS X, configure:

set editor /Applications/TextEdit.app/Contents/MacOS/TextEdit

Setting a Preference

set verbosity DEBUG

Listing Preferences

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

show preferences

Limitation

Icon

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.

Troubleshooting

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

Platform Problems

Problems loading the JLine DLL

On Windows, JLine (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: