Using GShell

GShell is a Groovy class that provides static methods allowing you to write and run Java and Groovy code from a shell environment such as MATLAB, Python, R or SciLab.

The code will be compiled on-the-fly and run in a Groovy shell.

GShell has been designed to allow code to be copy-and-pasted then run without editing between MATLAB, Python, R, SciLab etc. For example: 

                    value=GShell.eval('return new java.io.File("myfile.dat")')
works across all supported environments once GShell is set up. In MATLAB and Python that would be done by importing the GShell class. In R and SciLab, a GShell.eval function has been defined and this function will invoke the GShell method call.

The shell context

A groovy shell instance has a "context": essentially a workspace where you can create named variables and associate values with them. Java/Groovy scripts running in the shell have automatic access to these variables.

The GShell class provides static methods to add variables to the context and retrieve them from MATLAB, R etc.

As data transfer is bidirectional, GShell can also be used to share data between MATLAB, Python etc sessions if they share a Java Virtual Machine instance.

The following methods are available to exchange data:

  1. GShell.setVariable(name, value) - associates the value with a named variable.
  2. GShell.addVariables(Map) - creates a variable from each key in the Map and sets the value from the Map.
  3. GShell.addVariables(Object[]) - creates a variable named from the even numbered elements of the Object[] setting the values from the odd-numbered elements.
  4. value=GShell.getVariable(name) - returns the value of the named variable
  5. GShell.remove(name) - removes the named variable from the context
  6. GShell.clear()- removes all variables from the context
In addition, a LIFO stack of contexts is maintained. The current context can be pushed to the stack and restored using:
  1. GShell.push() - saves a copy then clears the current context
  2. GShell.pull() - restores the context

The current script

The shell can be associated with a "current script" initially set by loading it from a .groovy script file.
GShell.load(file name)

Compiled scripts can also be saved for later use (together with any binding associated with them - see below).

To do this, call:

GShell.putScript(name)

to save the current script. Use:
GShell.pullScript(name)

to retrieve a script that was previously saved. The current script can also be retrieved as a GroovyCodeSource instance using:
GShell.getSource()

Script bindings

Loaded scripts can have a "binding" associated with them individually. A binding is a context associated with the script, rather than the shell. When available, the will be used instead of the shell context.

Note: Groovy uses binding and context interchangeably. The distinction made here is only for clarity in these help pages.

The binding for the current script can be set with the following methods (which work as described above for the shell context):
  • setBinding(Map)
  • setBinding(Object[])
  • setBinding(Binding)
and supplemented with:
  • addToBinding(Map)
  • addToBinding(Object[])

Running scripts with the eval methods

The eval methods allow you to run arbitrary Groovy/Java code represented as a string. These methods can both return a result to the calling environment:
  • value=GShell.eval(...) runs the code on the current thread
  • value=GShell.evalEDT(...) runs the code on the event despatch thread and returns control only when the script completes. evalEDT cannot be called from the EDT.
In addition:
  • GShell.evalLater(...) queues the code to run on the event despatch thread and returns control immediately
  • GShell.evalQuery(...) queues the code to run the code on the event despatch thread. If the call to evalQuery is made from the EDT, it will pass the call to evalLater. Otherwise, it will pass the call to evalEDT.
Finally, two methods are provided to run a script within a specified context:
  • value=GShell.evalWith(..., context) runs the code on the current thread using the context provided rather than the default shell context
  • value=GShell.evalEDTWith(..., context) runs the code on the EDT using the context provided rather than the default shell context.

Running scripts from file

The run methods are similar to the eval methods but run the current script.
These methods can both return a result to the calling environment:
  • value=GShell.run() runs the code on the current thread
  • value=GShell.runEDT() runs the code on the event despatch thread and returns control only when the script completes. runEDT cannot be called from the EDT.
In addition:
  • GShell.runLater() queues the code to run on the event despatch thread and returns control immediately
  • GShell.runQuery() queues the code to run the code on the event despatch thread. If the call to runQuery is made from the EDT, it will pass the call to runLater. Otherwise, it will pass the call to runEDT.
Finally, two methods are provided to run a script within a specified context:
  • value=GShell.runWith(context) runs the code on the current thread using the context provided rather than the default shell context
  • value=GShell.runEDTWith(context) runs the code on the EDT using the context provided rather than the default shell context.

The GShell editor

Calling GShell.editor() displays a simple editor for creating and formatting Groovy scripts for use with the eval methods. There are two problems with creating portable code:
  1. String delimiters - for best portability use single quotes as the outer-delimiters for the code and double quotes to delimit strings inside the code.
  2. Line continuation - the line continuation convention is different between e.g. MATLAB and Python
If the GShell.editor is used to write the code, the Format button will automatically adjust quotes and line breaks.

Choosing Copy or Run additionally minifies the code so that it occupies a single line with semi-colons replacing line-breaks.