help/html/features/groovy.html

   1 <html>
   2 <!--
   3  * Jalview - A Sequence Alignment Editor and Viewer (Version 2.8)
   4  * Copyright (C) 2012 J Procter, AM Waterhouse, LM Lui, J Engelhardt, 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 <head>
  20 <title>Groovy Shell</title>
  21 </head>
  22 <body>
  23         <p>
  24                 <strong>The Groovy Shell</strong>
  25         </p>
  26         <p>
  27                 <a href="http://groovy.codehaus.org/">Groovy</a> is an &quot;<em>agile
  28                         and dynamic language for the Java platform</em>&quot;. The groovy
  29                 scripting language makes it extremely easy to programmatically
  30                 interact with Java programs, in much the same way that Javascript is
  31                 used to generate and interact with applets and other objects on the
  32                 page.
  33         </p>
  34         <p>
  35                 <strong><em>Getting Groovy...</em>
  36                 </strong><br> Jalview Groovy support is only possible if the core groovy
  37                 jars which include the GroovyShell are present on the CLASSPATH when
  38                 Jalview is started.
  39         </p>
  40         <p>
  41                 The jars are obtained from the <em>embedded</em> directory within the
  42                 <a href="http://dist.codehaus.org/groovy/distributions">groovy
  43                         distribution</a>. The easiest way of adding them to the Jalview classpath
  44                 is to download and build jalview from it's source distribution, and
  45                 then add the groovy-all-*.jar to the lib directory whose path is given
  46                 in the java.ext.dirs property.
  47         </p>
  48         <p>
  49                 <strong>Opening Jalview's Groovy Console</strong><br>If groovy is
  50                 available, then the <strong>Tools&#8594;Groovy Console...</strong>
  51                 menu entry will be available from the Jalview Desktop's drop-down
  52                 menu. Selecting this will open the <a
  53                         href="http://groovy.codehaus.org/Groovy+Console">Groovy Console</a>
  54                 which allows you to interactively execute Groovy scripts within the
  55                 Jalview run-time environment.
  56         </p>
  57         <p>
  58                 <strong>Executing groovy scripts on Jalview startup</strong><br>
  59                 The -groovy &lt;script&gt; option on the <a href="commandline.html" />
  60                 Jalview command line</a> will execute the contents of &lt;script&gt;.
  61                 &lt;script&gt; may be a file, a URL, or alternatively if it is
  62                 &quot;STDIN&quot; then the standard input will be used.<br>
  63                 <em>Note: The groovy script will be executed <strong>after</strong>
  64                         any data is loaded, and <strong>before</strong> images or any output
  65                         files are written. This allows you to perform customised jalview
  66                         analysis workflows with groovy.</em>
  67         </p>
  68         <p>
  69                 <strong>Access to Jalview's functions from Groovy Scripts</strong><br>
  70                 There is as yet no properly defined scripting interface to Jalview,
  71                 but all the public methods of the jalview class hierarchy can be
  72                 called from Groovy scripts. The access point for this is the <strong>Jalview</strong>
  73                 object defined in the groovy environent which corresponds to the
  74         <pre>jalview.gui.Desktop</pre>
  75         object which manages all the Jalview windows.
  76         </p>
  77         Here's an example to get you started:
  78         <br>
  79         <ul>
  80                 <li>Getting the title, alignment and first sequence from the
  81                         current alignFrame<br> <pre>
  82 def alf = Jalview.getAlignframes();
  83 print alf[0].getTitle();
  84 def alignment = alf[0].viewport.alignment;
  85 def seq = alignment.getSequenceAt(0);
  86 </pre></li>
  87 <li>When running a groovy script from the command line, the alignment that was just loaded can be referred to like so:<br><pre>
  88 print currentAlFrame.getTitle();</pre>
  89         </ul>
  90         </p>
  91
  92         <p>&nbsp;</p>
  93 </body>
  94 </html>