JAL-2416 score matrix gap symbol (if any) dynamically determined
[jalview.git] / help / html / features / groovy.html
1 <html>
2 <!--
3  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
4  * Copyright (C) $$Year-Rel$$ The Jalview Authors
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
11  * of the License, or (at your option) any later version.
12  *  
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.
17  * 
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.
21  -->
22 <head>
23 <title>Groovy Shell</title>
24 </head>
25 <body>
26   <p>
27     <strong>The Groovy Shell</strong>
28   </p>
29   <p>
30     Groovy (<a href="http://www.groovy-lang.org/">www.groovy-lang.org</a>)
31     is an &quot;<em>agile and dynamic language for the Java
32       platform</em>&quot;. The groovy scripting language makes it extremely
33     easy to programmatically interact with Java programs, in much the
34     same way that Javascript is used to generate and interact with
35     applets and other objects on the page.
36   </p>
37   <p>
38     <em>Getting Groovy...</em><br> Jalview comes with an embedded
39     installation of Groovy. Just select <strong>Tools&#8594;Groovy
40       Console...</strong> from the Jalview Desktop's drop-down menu. After a
41     short pause, you should then see the <a
42       href="http://groovy-lang.org/groovyconsole.html">Groovy
43       Console</a> appear. This allows you to interactively execute Groovy
44     scripts whilst Jalview is running. We've also provided a <strong>Calculations&#8594;Execute
45       Groovy Script</strong> button so you can execute the currently loaded
46     groovy script whilst viewing an alignment.
47   </p>
48   <p>
49     <strong>Executing groovy scripts on Jalview startup</strong><br>
50     The -groovy &lt;script&gt; option on the <a href="commandline.html">
51       Jalview command line</a> will execute the contents of &lt;script&gt;.
52     &lt;script&gt; may be a file, a URL, or alternatively if it is
53     &quot;STDIN&quot; then the standard input will be used.<br> <em>Note:
54       The groovy script will be executed <strong>after</strong> any data
55       is loaded, and <strong>before</strong> images or any output files
56       are written. This allows you to perform customised Jalview
57       analysis workflows with groovy.
58     </em>
59   </p>
60   <p>
61     <strong>Access to Jalview's functions from Groovy Scripts</strong><br>
62     The scripting interface to Jalview is still a work in progress, so
63     we recommend you also take a look at Jalview's source, since all the
64     public methods of the jalview class hierarchy can be called from
65     Groovy scripts. In addition, the following objects are also defined:
66
67
68   
69   <ul>
70     <li><strong>Jalview</strong> - this is bound to <code>jalview.bin.Jalview</code>.<br />Useful
71       methods include:
72       <ul>
73         <li>Jalview.getAlignFrames() - returns a list of
74           jalview.gui.AlignFrame objects</li>
75         <li>Jalview.getCurrentAlignFrame() - returns the alignment
76           window which is currently being looked at by the user</li>
77       </ul></li>
78     <li><strong>currentAlFrame</strong> - this is only defined when
79       running a Groovy script via the -groovy command line argument. It
80       returns the first alignment window created after acting on the
81       other arguments passed on the command line.</li>
82   </ul>
83   <p>
84     <em>A simple script</em><br />
85   <ul>
86     <li>Getting the title, alignment and first sequence from the
87       current alignFrame<br> <pre>
88 def alf = Jalview.getAlignFrames();
89 print alf[0].getTitle();
90 def alignment = alf[0].viewport.alignment;
91 def seq = alignment.getSequenceAt(0);
92 </pre>
93     </li>
94     <li>If you wanted to do the same thing from the command line,
95       you can refer to alignment that was just loaded with
96       currentAlFrame:<br> <pre>
97 print currentAlFrame.getTitle();</pre>
98   </ul>
99   <p>
100     <em>Example scripts</em><br />If you have downloaded the
101     InstallAnywhere version of Jalview, you can find additional groovy
102     scripts in the examples/groovy subfolder of the installation
103     directory. The examples are also available at <a
104       href="http://www.jalview.org/examples/groovy">http://www.jalview.org/examples/groovy</a>.
105   </p>
106   <p>
107     <em>Using Groovy to add new Alignment Calculations</em><br />We've
108     simplified the alignment analysis programming interface in Jalview
109     2.10 to make it easy for you to add your own dynamic annotation
110     tracks with Groovy. Have a look at the <a
111       href="../groovy/featureCounter.html">featureCounter.groovy</a>
112     example for more information.
113   </p>
114
115 </body>
116 </html>