3 .\" $Id: sw-env.5,v 1.2 1999/07/16 12:45:37 mdw Exp $
5 .\" Manual page for `sw-env' files
10 .\"----- Licensing notice ---------------------------------------------------
12 .\" This file is part of sw-tools.
14 .\" sw-tools is free software; you can redistribute it and/or modify
15 .\" it under the terms of the GNU General Public License as published by
16 .\" the Free Software Foundation; either version 2 of the License, or
17 .\" (at your option) any later version.
19 .\" sw-tools is distributed in the hope that it will be useful,
20 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
21 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 .\" GNU General Public License for more details.
24 .\" You should have received a copy of the GNU General Public License
25 .\" along with sw-tools; if not, write to the Free Software Foundation,
26 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 .\"----- Revision history ---------------------------------------------------
30 .\" $Log: sw-env.5,v $
31 .\" Revision 1.2 1999/07/16 12:45:37 mdw
32 .\" Internal formatting improvements.
34 .\" Revision 1.1 1999/06/04 13:56:18 mdw
38 .\" --- Useful macro definitions ---
40 .de VS \" Start a sort-of verbatim block
46 .de VE \" Stop a sort-of verbatim block
52 .de hP \" Start an indented paragraph with a bold right-aligned label
54 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
57 .\" --- Style hacking ---
61 . ds mw \fR[\f(BImdw\fR]
63 .el .ds mw \fR[\fBmdw\fR]
69 .\"----- Main manual text ---------------------------------------------------
71 .TH sw 1 "25 May 1999" "EBI tools"
74 .\"--------------------------------------------------------------------------
78 sw\-env \- environment variable assignment files for \*(sw.
80 .\"--------------------------------------------------------------------------
84 A \*(se file is a sequence of statements. The following statements are
114 Whitespace serves to separate tokens but is otherwise ignored except
115 when it occurs quoted within a
117 The file may also contain comments, which begin with a
119 character and extend to the end of the line. The start of a comment
120 must appear where a new statement is expected. Apart from its behaviour
121 of terminating comments, newlines behave the same way as other
122 whitespace characters. Keywords are not reserved words.
126 is a sequence of digits, letters and underscores which does not start
131 may contain any non-null character, although some characters are special
132 and must be quoted. The syntax of
134 is loosely based on the Bourne
135 shell, although there are differences and irregularities due to the
136 quick and dirty nature of the parser. The various quoting and
137 substitution operations are described below.
141 The statements behave as follows:
146 is read and discarded. This is not useless: reading a
148 may cause variables to be assigned as a result of
150 .BI ${ name = value }\c
156 is read, and further assignments are read from the file so named, if it
157 exists. Conventionally, the last statement in the global \*(se file is
161 to read in package-specific settings.
166 is read. If it matches the name of the host's architecture, then the
167 brace-enclosed statements are executed; otherwise they're ignored. It's
168 possible, though not useful, to nest
177 are read, optionally separated by an
179 character. The variable named is assigned the value, replacing any
180 previously assigned value, if any. The
182 keyword is optional. It's only useful so that you can assign values to
183 variables whose names are also statement keywords.
188 is read. Any value assigned to the variable named is discarded, and the
189 variable is forgotten.
193 The parser usually reads a
195 a character by character, until it finds a delimiter. Delimiter
203 whitespace also acts as a delimiter. Delimiter characters can only
204 appear in a value if quoted.
206 There are three types of quoting understood by the value reader. A
209 character causes the following character to be stripped of its special
212 inserts a literal backslash. Text between single quotes
215 entirely as-is, including all whitespace, newlines, backslashes,
216 everything. To include a single quote in a piece of single-quoted text,
219 as in the shell. (This drops out of single-quoting, inserts an escaped
220 single quote, and resumes quoting.) Text between double quotes
222 is partially quoted: delimiters and whitespace are read as normal
223 characters, but substitutions using the
227 characters are still made, and the backslash retains its behaviour of
228 escaping the following character.
230 Two sorts of substitutions are available in values:
231 .I "variable substitution"
232 examines a variable and substitutes some text based on its value, and
233 .I "command substitution"
234 runs a command and substitutes its output.
236 The simplest variable substitution takes the form
239 this is replaced by the value of the variable called
241 or the empty string if there is no such variable defined. The name may
242 be enclosed in braces should it be necessary to clearly disambiguate the
245 More complex variable substitutions are permitted:
247 .BI ${ name \- text }
248 Expands to the value of the variable called
257 if there is a variable called
262 If there is no variable called
264 then create one with the value
266 then expands to the variable's value.
268 In each of the above, prefixing the operator character
275 changes the variable existence test, such that it will believe that a
276 variable whose value is the empty string is not defined. Each
278 part in the above forms is syntactically a
280 and may itself contain quoting and substitutions. It may also contain
281 unescaped whitespace.
283 There are two forms for command substitution: the backtick form, where a
284 command is enclosed in backquotes
286 and the parenthesized form
288 The only difference between these two forms is syntactic: it's easy to
289 make the parenthesized version nest, although that's not actually very
290 useful. The text between the backquotes or parentheses is broken into
291 words and executed as a command. It is not passed through the shell:
292 the author suspects that this would be too confusing. The standard
293 output of the command, with trailing newlines (but not internal or
294 leading newlines) removed, is the result of the substitution.
296 .\"--------------------------------------------------------------------------
300 The \*(sw program, and this manual, are \*(mw productions, in association
301 with the European Bioinformatics Institute. They were written by Mark
302 Wooding <mdw@nsict.org>. Go and ask him if you have problems.
304 .\"----- That's all, folks --------------------------------------------------