Groovy Shell

X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhtml%2Ffeatures%2Fgroovy.html;h=ead44369ef3f87aa2d19368b9056f2611a5880ac;hb=3c8a25936a2d805e7e3d7ab82f83b13135406d18;hp=3e7b0f4237bb29499428c530d109c373055819a0;hpb=79c34bea5d18899696e681e34eebd1c33fc1683b;p=jalview.git diff --git a/help/html/features/groovy.html b/help/html/features/groovy.html index 3e7b0f4..ead4436 100644 --- a/help/html/features/groovy.html +++ b/help/html/features/groovy.html @@ -1,50 +1,125 @@ - -Groovy Shell - -

The Groovy Shell

Groovy is an "agile and dynamic -language for the Java platform". The groovy scripting language makes it -extremely easy to programmatically interact with Java programs, in much the same -way that Javascript is used to generate and interact with applets and other -objects on the page.

Getting Groovy...
-Jalview Groovy support is only possible if the core groovy -jars which include the GroovyShell are present on the CLASSPATH -when Jalview is started.

The jars are obtained from the -embedded directory within the groovy -distribution. The easiest way of adding them to the -Jalview classpath is to download and build jalview from -it's source distribution, and then add the groovy-all-*.jar -to the lib directory whose path is given in the java.ext.dirs property.

Opening Jalview's Groovy Console
If groovy is available, then the -Tools→Groovy Console... menu entry will be available -from the Jalview Desktop's drop-down menu. Selecting this will open the -Groovy Console which -allows you to interactively execute Groovy scripts within the Jalview run-time environment.

Executing groovy scripts on Jalview startup
-The -groovy <script> option on the -Jalview command line will execute the contents of -<script>. <script> may be a file, or alternatively if it is "STDIN" -then the standard input will be used.

Access to Jalview's functions from Groovy Scripts
-There is as yet no properly defined scripting interface to Jalview, but all the -public methods of the jalview class hierarchy can be called from Groovy scripts. -The access point for this is the Jalview object defined in -the groovy environent which corresponds to the

jalview.gui.Desktop

object which -manages all the Jalview windows.

-Here's an example to get you started:
-

Getting the title, alignment and first sequence from the current alignFrame
-

-def alf = Jalview.getAlignframes();
-print alf[0].getTitle();
-def alignment = alf[0].viewport.alignment;
-def seq = alignment.getSequenceAt(0);
-

- -

- - + + + +Groovy Shell + + +

+ The Groovy Shell +

+ Groovy (www.groovy-lang.org) + is an "agile and dynamic language for the Java + platform". The groovy scripting language makes it extremely + easy to programmatically interact with Java programs, in much the + same way that Javascript is used to generate and interact with + applets and other objects on the page. +

+ Getting Groovy...
Jalview comes with an embedded + installation of Groovy. Just select Tools→Groovy + Console... from the Jalview Desktop's drop-down menu. After a + short pause, you should then see the Groovy + Console appear. This allows you to interactively execute Groovy + scripts whilst Jalview is running. We've also provided a Calculations→Execute + Groovy Script button so you can execute the currently loaded + groovy script whilst viewing an alignment. +

+ Executing groovy scripts on Jalview startup
+ The -groovy <script> option on the + Jalview command line will execute the contents of <script>. + <script> may be a file, a URL, or alternatively if it is + "STDIN" then the standard input will be used.
Note: + The groovy script will be executed after any data + is loaded, and before images or any output files + are written. This allows you to perform customised Jalview + analysis workflows with groovy. + +

+ Access to Jalview's functions from Groovy Scripts
+ The scripting interface to Jalview is still a work in progress, so + we recommend you also take a look at Jalview's source, since all the + public methods of the jalview class hierarchy can be called from + Groovy scripts. In addition, the following objects are also defined: + + + +

Jalview - this is bound to jalview.bin.Jalview.
Useful + methods include: +
- Jalview.getAlignFrames() - returns a list of + jalview.gui.AlignFrame objects
- Jalview.getCurrentAlignFrame() - returns the alignment + window which is currently being looked at by the user
currentAlFrame - this is only defined when + running a Groovy script via the -groovy command line argument. It + returns the first alignment window created after acting on the + other arguments passed on the command line.

+ A simple script
+

Getting the title, alignment and first sequence from the + current alignFrame

+def alf = Jalview.getAlignFrames();
+print alf[0].getTitle();
+def alignment = alf[0].viewport.alignment;
+def seq = alignment.getSequenceAt(0);
+

If you wanted to do the same thing from the command line, + you can refer to alignment that was just loaded with + currentAlFrame:
```
+print currentAlFrame.getTitle();
```
+

+ Example scripts
If you have downloaded the + InstallAnywhere version of Jalview, you can find additional groovy + scripts in the examples/groovy subfolder of the installation + directory. The examples are also available at http://www.jalview.org/examples/groovy. +

+ Using Groovy to add new Alignment Calculations
We've + simplified the alignment analysis programming interface in Jalview + 2.10 to make it easy for you to add your own dynamic annotation + tracks with Groovy. Have a look at the featuresCounter.groovy + example for more information. +

+ Creating custom colourschemes
+ You can create your own alignment colourschemes with a groovy script. We've provided two examples:
+

colourConserved.groovy creates an 'Conserved' colourscheme - similar to the classic GeneDOC shading model.
colourUnconserved.groovy creates an 'Unconserved' colourscheme, where any unconserved residues are coloured pink.

+ + +