fix for JAL-527
[jalview.git] / doc / AddingGroovySupport.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.5)
4  * Copyright (C) 2010 J Procter, AM Waterhouse, G Barton, M Clamp, S Searle
5  * 
6  * This file is part of Jalview.
7  * 
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 of the License, or (at your option) any later version.
11  * 
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
18 -->
19 <title>Adding Groovy Support to Jalview
20 </title>
21 <body>
22 <h1>
23 Adding Groovy Support to Jalview
24 </h1>
25 <p>
26 There is currently no scripting language 
27 extension within Jalview, in part because a 
28 scripting API has not yet been developed.
29 </p>
30 <p>It is, however, really easy to embed scripting
31 engines like groovy. If groovy is detected on the 
32 classpath, a new menu entry on the Desktop's Tools 
33 menu will open the GroovyShell.
34 </p>
35 <p>Here are some scripts to get you started:</p>
36 <ul><li>Getting the title, alignment and first sequence from the current alignFrame<br>
37 <pre>
38 def alf = Jalview.getAlignframes();
39 print alf[0].getTitle();
40 def alignment = alf[0].viewport.alignment;
41 def seq = alignment.getSequenceAt(0);
42 </pre>
43 </li>
44 </ul>
45 <h1>Getting Groovy...</h1>
46 <p>
47 You need the core groovy jars which include the GroovyShell. The easiest way of doing
48 this is to add the groovy-all-*.jar to the lib directory whose path is given in the java.ext.dirs property.</p>
49 <p>The is obtained from the <em>embedded</em> directory within the <a 
50 href="http://dist.codehaus.org/groovy/distributions"/>groovy distribution</a>).
51 </p>
52 <h2>TODO</h2>
53 <p>
54 Using Java class methods from Groovy is straightforward, but currently, there isn't a set of easy to use methods for the jalview objects. A Jalview Scripting API needs to be developed to make this easier.</p>
55 <h3>Making it easier</h3>
56 <p>jalview.bin.JalviewScript could be a top level jalview instance of a script execution thread, creating and maintaining the context for scripts operating on the jalview datamodel and interfacing with the Jalview GUI.
57 </p> 
58 </body>
59 </html>
60