help/help/html/features/clarguments-advanced.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 <title>Jalview Command Line Arguments: advanced usage</title>
  23 <body>
  24
  25   <h1>Jalview Command Line Arguments: advanced usage</h1>
  26
  27   <p>
  28   <a href="clarguments.html">Jalview Command Line Arguments: summary</a>
  29   <br/>
  30   <a href="clarguments-intro.html">Jalview Command Line Arguments: introduction</a>
  31   <br/>
  32   <a href="clarguments-basic.html">Jalview Command Line Arguments: basic usage</a>
  33   <br/>
  34   Jalview Command Line Arguments: advanced usage
  35   <br/>
  36   <a href="clarguments-argfiles.html">Jalview Command Line Arguments: argfiles</a>
  37   </p>
  38
  39   <hr/>
  40
  41   <ul>
  42   <li><a href="#alignmentlinkedids">Alignment linked IDs</a></li>
  43   <li><a href="#moresubtitutions">More substitutions</a></li>
  44   <li><a href="#equalsseparatorandfileglobs">Equals separator and file globs</a></li>
  45   </ul>
  46
  47
  48   <h2><a name="alignmentlinkedids"></a>Alignment linked IDs</h2>
  49
  50   <p>
  51   Jalview's alignment related arguments are linked together using a <em>linked ID</em>.  In all of the basic usage examples this linked ID is assigned using a default formula of <code>JALVIEW:<em>n</em></code> where <em>n</em> starts at 0 and increments every time there is an <code>--open</code>ed file (or a first use of <code>--append</code>) or the <code>--new</code>argument is used.
  52   </p>
  53
  54   <p>
  55   When another alignment related argument is used, it is assigned the same linked ID.  When the <code>--all</code> argument is used, following alignment related arguments are applied to all linked IDs (made so far).
  56   </p>
  57
  58   <p>
  59   You can assign your own linked IDs to alignments that are opened from the command-line.  To do this put the linked ID in square brackets ('[', ']') <em>immediately following the argument (i.e. before any space or equals sign) like this:
  60   <pre>
  61   jalview --open[myId1] file1.fa --open[myId2] file2.fa --open[myId3] file3.fa --colour[myId1] gecos-flower --colour[myId2] gecos-blossom --colour[myId3] zappo --image "*.png" --headless
  62   </pre>
  63   </p>
  64
  65   <p>
  66   As you can see the arguments for one alignment do not need to be adjacent as they are when using the default assigned linked ID.
  67   </p>
  68
  69
  70   <h2><a name="moresubstitutions"></a>More substitutions</h2>
  71
  72   <p>
  73   In the <a href="clarguments-basic.html#substutions">basic usage document</a> we have a list of special strings that get replaced in output filename values with parts of input filename values.
  74   </p>
  75
  76   <p>
  77   There is also an incrementor integer value <code>{n}</code> that can be put into both linked IDs and filenames and works across different linked IDs.  Whenever you use <code>{n}</code> in a linked ID or filename value it is replaced with the current value of <em>n</em>.  The initial value is 0, and it can be incremented by using the argument <code>--npp</code> or <code>--n++</code>, or using a another substitution <code>{++n}</code> in either a linked ID or filename value which increments the value and is replaced with the new incremented value of <em>n</em>.
  78   </p>
  79
  80   <p>
  81   In the same way that the <code>--all</code> argument enables (some) following arguments to apply to all opened alignments so far, the special linked ID <code>{*}</code> will also apply an individual argument to all opened linked IDs.
  82   <pre>
  83   jalview --open[myId1] fileA.fa --open[myId2] fileB.fa --open[myId3] fileC.fa --colour[{*}] taylor --all --image tmp/image-{++n}.png --headless
  84   </pre>
  85   The above will produce an image <code>image-0.png</code> for the alignment in <code>fileA.fa</code>,  an image <code>image-1.png</code> for the alignment in <code>fileB.fa</code>, etc.
  86   </p>
  87
  88
  89   <h2><a name="equalsseparatorandfileglobs"></a>Equals separator and file globs</h2>
  90
  91   <p>
  92   When a Jalview command-line argument requires one (or more) values, you can use the usual space separation, which allows the shell to expand any filename "globs" (or wildcards representing multiple files).  To Jalview this appears like a list of filenames supplied to the argument.
  93   </p>
  94
  95   <p>
  96   There is a limitation to shell expansion of file globs, as the length of a single command is limited (to different amounts depending on your shell and its configuration).
  97   </p>
  98
  99   <p>
 100   Jalview will also recognise values supplied to arguments (that expect one or more value) that are separated by an equals sign ("=").  There should be no spaces around the equals sign, e.g.
 101   <pre>
 102   jalview --open=examples/uniref50*.fa --colour=clustal --all --image=*.png --scale=2.5 --headless
 103   </pre>
 104   </p>
 105
 106   <p>
 107   One benefit of this is seen above in the <code>--image</code> argument, the special "alloutput" wildcard filename <code>*.png</code> will not be expanded by the shell, so does not need to be escaped or surrounded with quotation marks.
 108   </p>
 109
 110   <p>
 111   Another benefit is that the <em>input</em> filename
 112
 113   </p>
 114
 115
 116   <hr/>
 117   Continue to <a href="clarguments-argfiles.html">Jalview Command Line Arguments: argfiles</a>.
 118   <br/>
 119   Return to <a href="clarguments.html">Jalview Command Line Arguments: summary</a>.
 120
 121
 122 </body>
 123 </html>