Groovy Shell

X-Git-Url: http://source.jalview.org/gitweb/?a=blobdiff_plain;f=help%2Fhtml%2Ffeatures%2Fgroovy.html;h=ead44369ef3f87aa2d19368b9056f2611a5880ac;hb=cd5042310088854fc941b55011fd152f463b982b;hp=56ec86cc01d70d63edb6b1bc8d2fa2575dabcd0d;hpb=865a855a4ca87eadb3e5ff284ed32ed307d9c34b;p=jalview.git diff --git a/help/html/features/groovy.html b/help/html/features/groovy.html index 56ec86c..ead4436 100644 --- a/help/html/features/groovy.html +++ b/help/html/features/groovy.html @@ -1,95 +1,125 @@ + --> Groovy Shell -

- The Groovy Shell -

- Groovy is an "agile - and dynamic language for the Java platform". The groovy - scripting language makes it extremely easy to programmatically - interact with Java programs, in much the same way that Javascript is - used to generate and interact with applets and other objects on the - page. -

- Getting Groovy... -
Jalview Groovy support is only possible if the core groovy - jars which include the GroovyShell are present on the CLASSPATH when - Jalview is started. -

- The jars are obtained from the embedded directory within the - groovy - distribution. The easiest way of adding them to the Jalview classpath - is to download and build jalview from it's source distribution, and - then add the groovy-all-*.jar to the lib directory whose path is given - in the java.ext.dirs property. -

- Opening Jalview's Groovy Console
If groovy is - available, then the Tools→Groovy Console... - menu entry will be available from the Jalview Desktop's drop-down - menu. Selecting this will open the Groovy Console - which allows you to interactively execute Groovy scripts within the - Jalview run-time environment. -

- Executing groovy scripts on Jalview startup
- The -groovy <script> option on the - Jalview command line will execute the contents of <script>. - <script> may be a file, a URL, or alternatively if it is - "STDIN" then the standard input will be used.
- Note: The groovy script will be executed after - any data is loaded, and before images or any output - files are written. This allows you to perform customised jalview - analysis workflows with groovy. -

- Access to Jalview's functions from Groovy Scripts
- There is as yet no properly defined scripting interface to Jalview, - but all the public methods of the jalview class hierarchy can be - called from Groovy scripts. The access point for this is the Jalview - object defined in the groovy environent which corresponds to the -

jalview.gui.Desktop

- object which manages all the Jalview windows. -

- Here's an example to get you started: -
-

Getting the title, alignment and first sequence from the - current alignFrame

-def alf = Jalview.getAlignframes();
+  
+    The Groovy Shell
+  
+  
+    Groovy (www.groovy-lang.org)
+    is an "agile and dynamic language for the Java
+      platform". The groovy scripting language makes it extremely
+    easy to programmatically interact with Java programs, in much the
+    same way that Javascript is used to generate and interact with
+    applets and other objects on the page.
+  
+  
+    Getting Groovy...
 Jalview comes with an embedded
+    installation of Groovy. Just select Tools→Groovy
+      Console... from the Jalview Desktop's drop-down menu. After a
+    short pause, you should then see the Groovy
+      Console appear. This allows you to interactively execute Groovy
+    scripts whilst Jalview is running. We've also provided a Calculations→Execute
+      Groovy Script button so you can execute the currently loaded
+    groovy script whilst viewing an alignment.
+  
+  
+    Executing groovy scripts on Jalview startup

+    The -groovy <script> option on the 
+      Jalview command line will execute the contents of <script>.
+    <script> may be a file, a URL, or alternatively if it is
+    "STDIN" then the standard input will be used.
 Note:
+      The groovy script will be executed after any data
+      is loaded, and before images or any output files
+      are written. This allows you to perform customised Jalview
+      analysis workflows with groovy.
+    
+  
+  
+    Access to Jalview's functions from Groovy Scripts

+    The scripting interface to Jalview is still a work in progress, so
+    we recommend you also take a look at Jalview's source, since all the
+    public methods of the jalview class hierarchy can be called from
+    Groovy scripts. In addition, the following objects are also defined:
+
+
+  
+  

+    Jalview - this is bound to jalview.bin.Jalview.
Useful
+      methods include:
+      
+        Jalview.getAlignFrames() - returns a list of
+          jalview.gui.AlignFrame objects
+        Jalview.getCurrentAlignFrame() - returns the alignment
+          window which is currently being looked at by the user
+      
+    currentAlFrame - this is only defined when
+      running a Groovy script via the -groovy command line argument. It
+      returns the first alignment window created after acting on the
+      other arguments passed on the command line.
+  
+  
+    A simple script

+  

+    Getting the title, alignment and first sequence from the
+      current alignFrame
 +def alf = Jalview.getAlignFrames();
 print alf[0].getTitle();
 def alignment = alf[0].viewport.alignment;
 def seq = alignment.getSequenceAt(0);
-
-When running a groovy script from the command line, the alignment that was just loaded can be referred to like so:
+
+    
+    If you wanted to do the same thing from the command line,
+      you can refer to alignment that was just loaded with
+      currentAlFrame:
  print currentAlFrame.getTitle();
-	
-	
+

+ Example scripts
If you have downloaded the + InstallAnywhere version of Jalview, you can find additional groovy + scripts in the examples/groovy subfolder of the installation + directory. The examples are also available at http://www.jalview.org/examples/groovy. +

+ Using Groovy to add new Alignment Calculations
We've + simplified the alignment analysis programming interface in Jalview + 2.10 to make it easy for you to add your own dynamic annotation + tracks with Groovy. Have a look at the featuresCounter.groovy + example for more information. +

+ Creating custom colourschemes
+ You can create your own alignment colourschemes with a groovy script. We've provided two examples:
+

colourConserved.groovy creates an 'Conserved' colourscheme - similar to the classic GeneDOC shading model.
colourUnconserved.groovy creates an 'Unconserved' colourscheme, where any unconserved residues are coloured pink.