help/help/html/features/clarguments-argfiles.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>Command Line: argument files</title>
  23 <body>
  24
  25   <h1>Command Line: argument files</h1>
  26
  27   <p>
  28   <a href="clarguments.html">Command Line: introduction</a>
  29   <br/>
  30   <a href="clarguments-basic.html">Command Line: basic usage</a>
  31   <br/>
  32   <a href="clarguments-advanced.html">Command Line: advanced usage</a>
  33   <br/>
  34   <a href="clarguments-argfiles.html">Command Line: argument files</a>
  35   <br/>
  36   <a href="clarguments-reference.html">Command Line: reference</a>
  37   </p>
  38
  39   <hr/>
  40
  41   <ul>
  42   <li><a href="#argumentfiles">Argument files</a></li>
  43   <li><a href="#onlyargumentfiles">Only argument files</a></li>
  44   <li><a href="#evenmoresubstitutions">Even more substitutions</a></li>
  45   </ul>
  46
  47   <h2><a name="argumentfiles"></a>Argument files</h2>
  48
  49   <p>
  50   If you want to save a set of arguments to reuse, you can save them in a text file, say <code>argfile.txt</code>, and read them into Jalview with
  51   <pre>
  52   jalview --argfile=argfile.txt
  53   </pre>
  54   </p>
  55
  56   <p>
  57   The argument file has one argument and value per line, still using the double-dash ('--') before the argument name, and separating the argument and value with an equals sign ('=').
  58   <br/>
  59   Because the argument file is read by the application and not read by the shell, you do not need to escape any values -- all spaces will be read as part of the value until the end of the line.
  60   <br/>
  61   You can add comments to a line by starting the line with an hash (octothorpe, pound-sign '#').
  62   <br/>
  63   e.g.
  64   <table border="1">
  65   <tr>
  66   <td>
  67   File <code>argfile.txt</code>
  68   </td>
  69   </tr>
  70   <tr>
  71   <td>
  72   <pre>
  73 --nonews
  74 --nosplash
  75 --open=[nowrap,colour=gecos-flower,showannotations]examples/plantfdx.fa
  76 --features=examples/plantfdx.features
  77 --annotations=examples/plantfdx.annotations
  78 --image=images/alignment.png
  79 --scale=2.5
  80 #--scale=10
  81 # let's see what's happening
  82 #--headless</pre>
  83   </td>
  84   </tr>
  85   </table>
  86   </p>
  87
  88   <p>
  89   Because <code>&#8209;&#8209;argfiles</code> takes a filename argument, and multiple <code>&#8209;&#8209;argfiles</code> can be read on the command line, you can also use file globs to specify multiple <code>&#8209;&#8209;argfile</code> values.  If you produce an argument file for each set of alignment files that you wish to associate then you can act on all of them with, e.g.
  90   <pre>
  91   jalview --argfile=*/argfile.txt --headless
  92   </pre>
  93   </p>
  94
  95   <p>
  96   You can even read argument files from within argument files, e.g.
  97   <pre>
  98   jalview --argfile=argfile*.txt --headless
  99   </pre>
 100   <table border="1">
 101   <tr><td>File <code>argfile1.txt</code></td></tr>
 102   <tr><td><pre>
 103 --open=file1.fa
 104 --argfile=myfavouriteformattingargfile.txt
 105 --argfile=mysecondfavouriteimageargfile.txt</pre></td></tr>
 106   <tr><td>File <code>myfavouriteformattingargfile.txt</code></td></tr>
 107   <tr><td><pre>
 108 --wrap
 109 --showannotations
 110 --annotations={dirname}/{basename}.annots</pre></td></tr>
 111   <tr><td>File <code>mysecondfavouriteimageargfile.txt</code></td></tr>
 112   <tr><td><pre>
 113 --image=images/{basename}.png
 114 --width=1920
 115 --height=1080</pre></td></tr>
 116   </table>
 117   </p>
 118
 119   <p>
 120   If an argument file that has already been read is found in a firther argument file, then Jalview will exit with a warning.  This is to avoid loops of argument files.
 121   </p>
 122
 123
 124   <h2><a name="onlyargumentfiles"></a>Only argument files</h2>
 125
 126   <p>
 127   When you use an <code>&#8209;&#8209;argfile</code> argument, all other non-initialising arguments on the command line <em>will be ignored</em>.  Only the initialising arguments and any and all <code>&#8209;&#8209;argfiles</code> arguments on the command line will be used.  You can also set initialising arguments in argument files.
 128   </p>
 129
 130
 131   <h2><a name="evenmoresubstitutions"></a>Even more substitutions</h2>
 132
 133   <p>
 134   When adding values that can use substitutions within argument files, there are two additional substitutions that can be made:
 135   <br/>
 136   <code>{argfilebasename}</code> - replaced with the base of the filename of the argument file (i.e. without directory path or file extension).
 137   <br/>
 138   <code>{argfiledirname}</code> - replaced with the path to the filename of the argument file.
 139   </p>
 140
 141   <p>
 142   Another substitution you can make in argument files is the <code>{n}</code> substitution.  Combined with an <code>-npp</code> increment at the start (or end) of the argument file gives the potential to reuse an argument files in the same command but referring to different files, e.g.
 143
 144   <table border="1">
 145   <tr><td>File <code>alignment.argfile</code></td></tr>
 146   <tr><td><pre>
 147 --open={argfilebasename}-{n}.fa
 148 --wrap
 149 --output={basename}.stk
 150 --close
 151 --npp</pre></td></tr>
 152   </table>
 153   <pre>
 154   jalview --argfile alignment.argfile --argfile alignment.argfile --headless
 155   </pre>
 156   would be processed the same as
 157   <pre>
 158   jalview --open=alignment-0.fa --wrap --output=alignment-0.stk --close --open=alignment-1.fa --wrap --output=alignment-1.stk --close --headless
 159   </pre>
 160   </p>
 161
 162
 163   <hr/>
 164   <a href="clarguments-reference.html">Command Line: reference</a>
 165
 166
 167 </body>
 168 </html>