JAL-1551 spotlessApply
[jalview.git] / 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: summary</a>
29   <br/>
30   <a href="clarguments-intro.html">Command Line: introduction</a>
31   <br/>
32   <a href="clarguments-basic.html">Command Line: basic usage</a>
33   <br/>
34   <a href="clarguments-advanced.html">Command Line: advanced usage</a>
35   <br/>
36   Command Line: argument files
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 octothorpe (hash, 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>--argfiles</code> takes a filename argument, and multiple <code>--argfiles</code> can be read on the command line, you can also use file globs to specify multiple <code>--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 a "loop" of argument files is detected then Jalview will refuse to play (which is a Good Thing).
121   </p>
122
123
124   <h2><a name="onlyargumentfiles"></a>Only argument files</h2>
125
126   <p>
127   When you use an <code>--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>--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 are 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 amusing 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, which gives the potential of having multiple argument files with the exact same content, or even re-using the same argument file multiple times. 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 like
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   Return to <a href="clarguments.html">Command Line: summary</a>.
165
166
167 </body>
168 </html>