groovysh & groovyconsole

groovysh reads a line and decides whether it is a complete expression, statement or definition. If not, it prompts for more; if so, it compiles and runs it and prints the result, then stores that result in the shared variable _. Each input is run in isolation. The exceptions to that rule are what makes the shell usable:

In interpreter mode the shell behaves as if the remembered definitions were pasted before every input, so local variables and methods survive. With the mode off, a def variable is forgotten at the end of its input, and a method becomes a closure stored in the shared variables. In the installation used for this page, 6.0.0, the mode was on by default, as the GROOVYSH_OPTIONS entry of /show confirms ([interpreterMode:true]). A session in the default mode:

The commands /imports, /types, /vars and /methods list what has been remembered, each with a -d option that deletes entries; /del name deletes a name of any kind. An exception is printed in short form, and its details are kept in a shared variable called exception. Setting the mode off changes the behaviour as the documentation describes:

The lines elided with ... are the shell’s own variables (the console options, the working directory and _). The shared variable b survives, and so does the method hello, but as a closure in the same namespace as the variables; the local a is gone. The advice in the documentation follows: in the non-interpreter mode, treat local variables as immutable, and keep what you need in shared variables. In interpreter mode, remember that each def x = [] is replayed before every later input, so an earlier mutation of x is undone; the documentation gives the example of def fruit = [] followed by fruit << 'peach' and fruit << 'pear', after which fruit is empty again.

Source: Groovy documentation: groovysh, REPL model

Commands start with a slash and have help text: /help lists them, and /help /name or /name --help explains one. Some have system aliases such as /h. groovysh keeps its own notion of the working directory, so /cd and /pwd affect the file commands but not the JVM’s directory; the shared variable PWD helps when you shell out with /!. In 6.0.0 the commands are:

A few of them are worth a closer look.

Press Tab to complete class, property, method and command names, including your own types. History persists in the groovysh_history file of the .groovy directory in the home directory, as seen in the scratch run, and /history lists it:

The first lines, truncated here, show the earlier entries with their numbers. /show lists shared variables, and /ls and /pwd the working directory.

JLine’s widget system is how keys are bound to line-editing actions. groovysh includes the standard ones (word movement, kill and yank) and two optional ones: tailtip, which shows completions and a usage window as you type, and autosuggest, which proposes the rest of a line from your history. They are off by default; /widget -l lists them, /keymap shows the keys bound to the tailtip-toggle and autosuggest-toggle widgets, and both can be on at once.

An application that hosts groovysh (a domain console, say) uses Main.start(GroovyshOptions, String[]) rather than copying Main. The GroovyshOptions builder, which the documentation marks as incubating, sets the banner, prompt, bindings, extra command groups, result and error handlers, history file, and a hook for tuning the JLine reader. The following run hands the shell one variable, evaluates one expression, and collects the printed result instead of printing it:

(JLine printed four WARNING lines about restricted native access to standard error when the script started; they are harmless and can be silenced with --enable-native-access=ALL-UNNAMED.) Main.start(Map, String[]) still exists as the binding-only variant. To evaluate with compile-time customizers, create a GroovyEngine from a mutable CompilerConfiguration:

The output was engine ok. Use a copy of the default configuration, because the shared default instance must not be modified; an ASTTransformationCustomizer for @ThreadInterrupt is the usual addition so that Ctrl+C can stop a tight loop. The standard file commands (/ls, /cat, /grep, /wc and others) are in the public ExtraConsoleCommands class.

Source: Groovy documentation: groovysh, embedding

The dialog that appears while a script runs has an interrupt button. Interrupting only sets the thread’s interrupt flag, so a script stuck in a plain loop may go on running. Tick Script > Allow interruption to make the console apply the @ThreadInterrupt AST transformation to your script, which checks the flag in loops and method entries. The price is extra execution time for the checks. @ThreadInterrupt is one of the transformations on AST Transformations: Logging, Safety, Concurrency & Directives.

With View > Visualize Script Results ticked, a result that is a java.awt.Image, a javax.swing.Icon, or a parent-less java.awt.Component is displayed rather than shown as text. You can add your own transformations in ~/.groovy/OutputTransforms.groovy, a script that the console runs on startup with a transforms list in its binding. This example, from the documentation, shows a map as a table:

It was not run here, because it needs a display. The console remembers all of its settings with the Java Preferences API.

Source: Groovy documentation: groovyConsole, visualising script output results

The AST browser, opened from the Script menu, shows the syntax tree of the script being edited, together with the generated source and the bytecode. It is the quickest way to see what an AST transformation produced. The documentation’s example is a class annotated with @Immutable, whose generated equals appears in the Source tab, and the bytecode of the expression LocalDate.parse('2020/02/10', 'yyyy/MM/dd'). The CST browser shows the concrete syntax tree from the first parse and is mainly of use to people working on the parser. Writing your own transformations is covered on Writing AST Transformations & Macros.

A Java or Groovy application can embed the console, preload variables and open it:

The code is from the documentation and was not run here, as it opens a window. The variables are available to scripts typed into the console. The console is in the groovy-console module; see Integrating Groovy into Java Applications for the general mechanisms.

Source: Groovy documentation: groovyConsole, embedding the console