Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<h1>Groovy Shell</h1><p>The Groovy Shell, aka. <code>groovysh</code> is a command-line application which allows easy access to evaluate Groovy expressions, define classes and run simple experiments.</p><p><img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0zfG1pbkxldmVsPTJ9&amp;locale=en_GB&amp;version=2" data-macro-name="toc" data-macro-parameters="maxLevel=3|minLevel=2"></p><h2>Features</h2><ul><li>No need for <code>go</code> command to execute buffer.</li><li>Rich cross-platform edit-line editing, history and completion thanks to <a href="http://jline.sf.net">JLine</a>.</li><li>ANSI colors (prompt, exception traces, etc).</li><li>Simple, yet robust, command system with online help, user alias support and more.</li><li>User profile support</li></ul><h2>Command-line Options and Arguments</h2><p>The shell supports several options to control verbosity, ANSI coloring and other features.</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>./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
</pre></td></tr></table><p>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.</p><h5>Execute a Command</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>./bin/groovysh 'show preferences'
No preferences are set
</pre></td></tr></table><h5>Evaluate an Expression</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>./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
...
</pre></td></tr></table><h2>Evaluating Expressions</h2><h3>Simple Expressions</h3><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>println "Hello"
</pre></td></tr></table><h3>Evaluation Result</h3><p>When a complete expression is found, it is compiled and evaluated. The result of the evaluation is stored into the _ variable.</p><h3>Multi-line Expressions</h3><p>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.</p><h5>Define a Class</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>class Foo {
    def bar() {
        println "baz"
    }
}
</pre></td></tr></table><h5>Use the Class</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>foo = new Foo()
foo.bar()
</pre></td></tr></table><h3>Variables</h3><p>Shell variables are <strong>all</strong> untyped (ie. no <code>def</code> or other type information.</p><p>This <strong>will</strong> set a shell variable:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>foo = "bar"
</pre></td></tr></table><p>But, this will evaluate a local variable and will <strong>not</strong> be saved to the shell's environment:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>def foo = "bar"
</pre></td></tr></table><h3>Functions</h3><p>Functions can be defined in the shell, and will be saved for later use.</p><p>Defining a function is easy:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>groovy:000> def hello(name) {
groovy:001> println("Hello $name")
groovy:002> }
</pre></td></tr></table><p>And then using it is as one might expect:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>hello("Jason")
</pre></td></tr></table><table class="wysiwyg-macro" data-macro-name="note" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>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.</p></td></tr></table><h2>Commands</h2><p>The shell has a number of different commands, which provide rich access to the shell's environment.</p><p>Commands all have a <em>name</em> and a <em>shortcut</em> (which is something like <code>\h</code>). Commands may also have some predefined system <em>aliases</em>. Users may also create their own aliases.</p><h3>Recognized Commands</h3><h4><code>help</code></h4><p>Display the list of commands (and aliases) or the help text for specific command.</p><h5>The Command List</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>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 &lt;command>
</pre></td></tr></table><h5>Help for a Command</h5><p>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 <code>help</code> command:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>groovy:000> help help

usage: help [&lt;command>]

Display the list of commands or the help text for &lt;command>.
</pre></td></tr></table><h4><code>exit</code></h4><p>Exit the shell.</p><p>This is the <strong>only</strong> way to exit the shell. Well, you can still <code>CTRL-C</code>, but the shell will complain about an abnormal shutdown of the JVM.</p><h4><code>import</code></h4><p>Add a custom import which will be included for all shell evaluations.</p><p>This command can be given at any time to add new imports.</p><h4><code>display</code></h4><p>Display the contents of the current buffer.</p><p>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.</p><h5>Example</h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>groovy:000> class Foo {
groovy:001> def bar
groovy:002> def baz() {
groovy:003> display
 001> class Foo {
 002> def bar
 003> def baz() {
</pre></td></tr></table><h4><code>clear</code></h4><p><span>Clear</span><span class="x">s the current buffer, resetting the prompt counter to 000. Can be used to recover from compilation errors</span><span>.</span></p><h4><code>show</code></h4><p>Show variables, classes or preferences or imports.</p><h5><code>show variables</code></h5><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>groovy:000> show variables
Variables:
  _ = true
</pre></td></tr></table><h5><code>show classes</code></h5><h5><code>show imports</code></h5><h5><code>show preferences</code></h5><h5><code>show all</code></h5><h4><code>inspect</code></h4><p>Opens the GUI object browser to inspect a variable or the result of the last evaluation.</p><h4><code>purge</code></h4><p>Purges objects from the shell.</p><h5><code>purge variables</code></h5><h5><code>purge classes</code></h5><h5><code>purge imports</code></h5><h5><code>purge preferences</code></h5><h5><code>purge all</code></h5><h4><code>edit</code></h4><p>Edit the current buffer in an external editor.</p><p>Currently only works on UNIX systems which have the <code>EDITOR</code> environment variable set, or have configured the <code>editor</code> preference.</p><h4><code>load</code></h4><p>Load one or more files (or urls) into the buffer.</p><h4><code>save</code></h4><p>Saves the buffer's contents to a file.</p><h4><code>record</code></h4><p>Record the current session to a file.</p><h5><code>record start</code></h5><h5><code>record stop</code></h5><h5><code>record status</code></h5><h4><code>history</code></h4><p>Display, manage and recall edit-line history.</p><h5><code>history show</code></h5><h5><code>history recall</code></h5><h5><code>history flush</code></h5><h5><code>history clear</code></h5><h4><code>alias</code></h4><p>Create an alias.</p><h4><code>set</code></h4><p>Set or list preferences.</p><h2>Preferences</h2><p>Some of aspects of <code>groovysh</code> behaviors can be customized by setting preferences. Preferences are set using the <code>set</code> command or the <code>\=</code> shortcut.</p><h3>Recognized Preferences</h3><h4><code>verbosity</code></h4><p>Set the shell's verbosity level. Expected to be one of:</p><ul><li><code>DEBUG</code></li><li><code>VERBOSE</code></li><li><code>INFO</code></li><li><code>QUIET</code></li></ul><p>Default is <code>INFO</code>.</p><p>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.</p><h4><code>show-last-result</code></h4><p>Show the last result after an execution.</p><p>Default is <code>true</code>.</p><h4><code>sanitize-stack-trace</code></h4><p>Sanitize (trim-down/filter) stack traces.</p><p>Default is <code>true</code>.</p><h4><code>editor</code></h4><p>Configures the editor used by the <code>edit</code> command.</p><p>Default is the value of the system environment variable <code>EDITOR</code>.</p><table class="wysiwyg-macro" data-macro-name="tip" data-macro-parameters="title=Mac OS X" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e3RpcDp0aXRsZT1NYWMgT1MgWH0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>To use <code>TextEdit</code>, the default text editor on Mac OS X, configure:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>set editor /Applications/TextEdit.app/Contents/MacOS/TextEdit
</pre></td></tr></table></td></tr></table><h4>Setting a Preference</h4><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>set verbosity DEBUG
</pre></td></tr></table><h3>Listing Preferences</h3><p>To list the current <em>set</em> preferences (and their values):</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>show preferences
</pre></td></tr></table><table class="wysiwyg-macro" data-macro-name="note" data-macro-parameters="title=Limitation" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vdGU6dGl0bGU9TGltaXRhdGlvbn0&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"><p>At the moment, there is no way to list all of the known/available preferences to be set.</p></td></tr></table><h3>Clearing Preferences (ie. Resetting to Defaults)</h3><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>purge preferences
</pre></td></tr></table><h2>User Profile Scripts and State</h2><h3>Profile Scripts</h3><h4><code>$HOME/.groovy/groovysh.profile</code></h4><p>This script, if it exists, is loaded when the shell starts up.</p><h4><code>$HOME/.groovy/groovysh.rc</code></h4><p>This script, if it exists, is loaded when the shell enters interactive mode.</p><h3>State</h3><h4><code>$HOME/.groovy/groovysh.history</code></h4><p>Edit-line history is stored in this file.</p><h2>Screen Shots</h2><p>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 <em>bold</em> color, so the colors might look different depending on how the enclosing shell has its colors setup.</p><p><img class="confluence-embedded-image" src="/download/attachments/231080144/groovysh3.jpg?version=1&amp;modificationDate=1369397932003" data-image-src="/download/attachments/231080144/groovysh3.jpg?version=1&amp;modificationDate=1369397932003" data-linked-resource-id="231375690" data-linked-resource-type="attachment" data-linked-resource-default-alias="groovysh3.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080144" title="null > groovysh3.jpg" data-element-title="groovysh3.jpg"></p><p><img class="confluence-embedded-image" src="/download/attachments/231080144/groovysh2.jpg?version=1&amp;modificationDate=1369397931998" data-image-src="/download/attachments/231080144/groovysh2.jpg?version=1&amp;modificationDate=1369397931998" data-linked-resource-id="231375689" data-linked-resource-type="attachment" data-linked-resource-default-alias="groovysh2.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080144" title="null > groovysh2.jpg" data-element-title="groovysh2.jpg"></p><p><img class="confluence-embedded-image" src="/download/attachments/231080144/groovysh4.jpg?version=1&amp;modificationDate=1369397932004" data-image-src="/download/attachments/231080144/groovysh4.jpg?version=1&amp;modificationDate=1369397932004" data-linked-resource-id="231375691" data-linked-resource-type="attachment" data-linked-resource-default-alias="groovysh4.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="231080144" title="null > groovysh4.jpg" data-element-title="groovysh4.jpg"></p><h2>Troubleshooting</h2><p>Please <a href="http://jira.codehaus.org/browse/GROOVY">report</a> any problems you run into. Please be sure to mark the JIRA issue with the <code>Groovysh</code> component.</p><h3>Platform Problems</h3><h4>Problems loading the JLine DLL</h4><p>On Windows, <a href="http://jline.sf.net">JLine</a> (which is used for the fancy shell input/history/completion fluff), uses a <strong>tiny</strong> DLL file to trick the <strong>evil</strong> Windows faux-shell (<code>CMD.EXE</code> or <code>COMMAND.COM</code>) into providing Java with unbuffered input. In some rare cases, this might fail to load or initialize.</p><p>One solution is to disable the frills and use the unsupported terminal instance. You can do that on the command-line using the <code>--terminal</code> flag and set it to one of:</p><ul><li><code>none</code></li><li><code>false</code></li><li><code>off</code></li><li><code>jline.UnsupportedTerminal</code></li></ul><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>groovysh --terminal=none
</pre></td></tr></table><h4>Problems with Cygwin on Windows</h4><p>Some people have issues when running groovysh with cygwin. If you have troubles, the following may help:</p><table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>stty -icanon min 1 -echo
groovysh --terminal=unix
stty icanon echo
</pre></td></tr></table><p>wiki</p>