3 * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4 * Copyright (C) $$Year-Rel$$ The Jalview Authors
6 * This file is part of Jalview.
8 * Jalview is free software: you can redistribute it and/or
9 * modify it under the terms of the GNU General Public License
10 * as published by the Free Software Foundation, either version 3
11 * of the License, or (at your option) any later version.
13 * Jalview is distributed in the hope that it will be useful, but
14 * WITHOUT ANY WARRANTY; without even the implied warranty
15 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
16 * PURPOSE. See the GNU General Public License for more details.
18 * You should have received a copy of the GNU General Public License
19 * along with Jalview. If not, see <http://www.gnu.org/licenses/>.
20 * The Jalview Authors are detailed in the 'AUTHORS' file.
23 <title>Groovy Shell</title>
27 <strong>The Groovy Shell</strong>
30 <a href="http://groovy.codehaus.org/">Groovy</a> is an "<em>agile
31 and dynamic language for the Java platform</em>". The groovy
32 scripting language makes it extremely easy to programmatically
33 interact with Java programs, in much the same way that Javascript is
34 used to generate and interact with applets and other objects on the
38 <strong><em>Getting Groovy...</em> </strong><br> Jalview Groovy
39 support is only possible if the core groovy jars which include the
40 GroovyShell are present on the CLASSPATH when Jalview is started.
43 The jars are obtained from the <em>embedded</em> directory within
44 the <a href="http://dist.codehaus.org/groovy/distributions">groovy
45 distribution</a>. The easiest way of adding them to the Jalview
46 classpath is to download and build Jalview from its source
47 distribution, and then add the groovy-all-*.jar to the lib directory
48 whose path is given in the java.ext.dirs property.
51 <strong>Opening Jalview's Groovy Console</strong><br>If groovy
52 is available, then the <strong>Tools→Groovy
53 Console...</strong> menu entry will be available from the Jalview Desktop's
54 drop-down menu. Selecting this will open the <a
55 href="http://groovy.codehaus.org/Groovy+Console"
56 >Groovy Console</a> which allows you to interactively execute Groovy
57 scripts within the Jalview run-time environment.
60 <strong>Executing groovy scripts on Jalview startup</strong><br>
61 The -groovy <script> option on the <a href="commandline.html">
62 Jalview command line</a> will execute the contents of <script>.
63 <script> may be a file, a URL, or alternatively if it is
64 "STDIN" then the standard input will be used.<br> <em>Note:
65 The groovy script will be executed <strong>after</strong> any data
66 is loaded, and <strong>before</strong> images or any output files
67 are written. This allows you to perform customised Jalview
68 analysis workflows with groovy.
72 <strong>Access to Jalview's functions from Groovy Scripts</strong><br>
73 There is as yet no properly defined scripting interface to Jalview,
74 but all the public methods of the jalview class hierarchy can be
75 called from Groovy scripts. The access point for this is the <strong>Jalview</strong>
76 object defined in the groovy environent which corresponds to the
77 <pre>jalview.gui.Desktop</pre>
78 object which manages all the Jalview windows. Here's an example to get
82 <li>Getting the title, alignment and first sequence from the
83 current alignFrame<br> <pre>
84 def alf = Jalview.getAlignFrames();
85 print alf[0].getTitle();
86 def alignment = alf[0].viewport.alignment;
87 def seq = alignment.getSequenceAt(0);
90 <li>When running a groovy script from the command line, the
91 alignment that was just loaded can be referred to like so:<br>
93 print currentAlFrame.getTitle();</pre>
95 If you have downloaded the InstallAnywhere version of Jalview, you can
96 find additional groovy scripts in the examples/groovy subfolder of the
97 installation directory.