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     <a href="http://www.groovy-lang.org/">Groovy</a> is an &quot;<em>agile
  31       and dynamic language for the Java platform</em>&quot;. 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
  35     page.
  36   </p>
  37   <p>
  38     <strong><em>Getting Groovy...</em> </strong><br> Jalview comes with
  39     an embedded installation of Groovy. All you need is to select <strong>Tools&#8594;Groovy
  40       Console...</strong> menu option from the Jalview Desktop's
  41     drop-down menu. After a short pause, you should then see the <a
  42       href="http://groovy-lang.org/groovyconsole.html"
  43     >Groovy Console</a> appear. This allows you to interactively execute Groovy
  44     scripts within the Jalview run-time environment.
  45   </p>
  46   <p>
  47     <strong>Executing groovy scripts on Jalview startup</strong><br>
  48     The -groovy &lt;script&gt; option on the <a href="commandline.html">
  49       Jalview command line</a> will execute the contents of &lt;script&gt;.
  50     &lt;script&gt; may be a file, a URL, or alternatively if it is
  51     &quot;STDIN&quot; then the standard input will be used.<br> <em>Note:
  52       The groovy script will be executed <strong>after</strong> any data
  53       is loaded, and <strong>before</strong> images or any output files
  54       are written. This allows you to perform customised Jalview
  55       analysis workflows with groovy.
  56     </em>
  57   </p>
  58   <p>
  59     <strong>Access to Jalview's functions from Groovy Scripts</strong><br>
  60     There is as yet no properly defined scripting interface to Jalview,
  61     but all the public methods of the jalview class hierarchy can be
  62     called from Groovy scripts. The access point for this is the <strong>Jalview</strong>
  63     object defined in the groovy environment which corresponds to the
  64   <pre>jalview.gui.Desktop</pre>
  65   object which manages all the Jalview windows. Here's an example to get
  66   you started:
  67   <br>
  68   <ul>
  69     <li>Getting the title, alignment and first sequence from the
  70       current alignFrame<br> <pre>
  71 def alf = Jalview.getAlignFrames();
  72 print alf[0].getTitle();
  73 def alignment = alf[0].viewport.alignment;
  74 def seq = alignment.getSequenceAt(0);
  75 </pre>
  76     </li>
  77     <li>When running a groovy script from the command line, the
  78       alignment that was just loaded can be referred to like so:<br>
  79     <pre>
  80 print currentAlFrame.getTitle();</pre>
  81   </ul>
  82   If you have downloaded the InstallAnywhere version of Jalview, you can
  83   find additional groovy scripts in the examples/groovy subfolder of the
  84   installation directory.
  85 </body>
  86 </html>