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] [...]
-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
-classpath Specify where to find the class files - must
be first argument
-cp, --classpath Aliases for '-classpath'
-d, --debug Enable debug output
-e, --evaluate=arg Evaluate option first when starting
interactive session
-h, --help Display this help message
-q, --quiet Suppress superfluous output
-v, --verbose Enable verbose output
1.3. Evaluating Expressions
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.
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 :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.
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
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
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.
history
Display, manage and recall edit-line history.
history show
history recall
history flush
history clear
doc
Opens a browser with documentation for the provided class. For example:
groovy:000> :doc java.util.List http://docs.oracle.com/javase/7/docs/api/java/util/List.html http://docs.groovy-lang.org/2.4.2-SNAPSHOT/html/groovy-jdk/java/util/List.html
will open two windows (or tabs, depending on your browser):
-
one for the JDK documentation
-
one for the GDK documentation
1.5. Preferences
Some of 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.
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.codehaus.groovy.tools.shell.CommandSupport
class. For example:
import org.codehaus.groovy.tools.shell.CommandSupport
import org.codehaus.groovy.tools.shell.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
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.