3 .\" $Id: sw-env.5,v 1.1 1999/06/04 13:56:18 mdw Exp $
5 .\" Manual page for `sw-env' files
9 .\"----- Licensing notice ---------------------------------------------------
11 .\" This file is part of sw-tools.
13 .\" sw-tools is free software; you can redistribute it and/or modify
14 .\" it under the terms of the GNU General Public License as published by
15 .\" the Free Software Foundation; either version 2 of the License, or
16 .\" (at your option) any later version.
18 .\" sw-tools is distributed in the hope that it will be useful,
19 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
20 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 .\" GNU General Public License for more details.
23 .\" You should have received a copy of the GNU General Public License
24 .\" along with sw-tools; if not, write to the Free Software Foundation,
25 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27 .\"----- Revision history ---------------------------------------------------
29 .\" $Log: sw-env.5,v $
30 .\" Revision 1.1 1999/06/04 13:56:18 mdw
34 .\" --- Useful macro definitions ---
36 .de VS \" Start a sort-of verbatim block
42 .de VE \" Stop a sort-of verbatim block
48 .de HP \" Start an indented paragraph with a bold right-aligned label
50 \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
53 .\" --- Style hacking ---
57 . ds mw \fR[\f(BImdw\fR]
59 .el .ds mw \fR[\fBmdw\fR]
65 .\" --- Main manual text ---
67 .TH sw 1 "25 May 1999" "EBI tools"
71 sw\-env \- environment variable assignment files for \*(sw.
74 A \*(se file is a sequence of statements. The following statements are
104 Whitespace serves to separate tokens but is otherwise ignored except
105 when it occurs quoted within a
107 The file may also contain comments, which begin with a
109 character and extend to the end of the line. The start of a comment
110 must appear where a new statement is expected. Apart from its behaviour
111 of terminating comments, newlines behave the same way as other
112 whitespace characters. Keywords are not reserved words.
116 is a sequence of digits, letters and underscores which does not start
121 may contain any non-null character, although some characters are special
122 and must be quoted. The syntax of
124 is loosely based on the Bourne
125 shell, although there are differences and irregularities due to the
126 quick and dirty nature of the parser. The various quoting and
127 substitution operations are described below.
129 The statements behave as follows:
134 is read and discarded. This is not useless: reading a
136 may cause variables to be assigned as a result of
138 .BI ${ name = value }\c
144 is read, and further assignments are read from the file so named, if it
145 exists. Conventionally, the last statement in the global \*(se file is
149 to read in package-specific settings.
154 is read. If it matches the name of the host's architecture, then the
155 brace-enclosed statements are executed; otherwise they're ignored. It's
156 possible, though not useful, to nest
165 are read, optionally separated by an
167 character. The variable named is assigned the value, replacing any
168 previously assigned value, if any. The
170 keyword is optional. It's only useful so that you can assign values to
171 variables whose names are also statement keywords.
176 is read. Any value assigned to the variable named is discarded, and the
177 variable is forgotten.
179 The parser usually reads a
181 a character by character, until it finds a delimiter. Delimiter
189 whitespace also acts as a delimiter. Delimiter characters can only
190 appear in a value if quoted.
192 There are three types of quoting understood by the value reader. A
195 character causes the following character to be stripped of its special
198 inserts a literal backslash. Text between single quotes
201 entirely as-is, including all whitespace, newlines, backslashes,
202 everything. To include a single quote in a piece of single-quoted text,
205 as in the shell. (This drops out of single-quoting, inserts an escaped
206 single quote, and resumes quoting.) Text between double quotes
208 is partially quoted: delimiters and whitespace are read as normal
209 characters, but substitutions using the
213 characters are still made, and the backslash retains its behaviour of
214 escaping the following character.
216 Two sorts of substitutions are available in values:
217 .I "variable substitution"
218 examines a variable and substitutes some text based on its value, and
219 .I "command substitution"
220 runs a command and substitutes its output.
222 The simplest variable substitution takes the form
225 this is replaced by the value of the variable called
227 or the empty string if there is no such variable defined. The name may
228 be enclosed in braces should it be necessary to clearly disambiguate the
231 More complex variable substitutions are permitted:
233 .BI ${ name \- text }
234 Expands to the value of the variable called
243 if there is a variable called
248 If there is no variable called
250 then create one with the value
252 then expands to the variable's value.
254 In each of the above, prefixing the operator character
261 changes the variable existence test, such that it will believe that a
262 variable whose value is the empty string is not defined. Each
264 part in the above forms is syntactically a
266 and may itself contain quoting and substitutions. It may also contain
267 unescaped whitespace.
269 There are two forms for command substitution: the backtick form, where a
270 command is enclosed in backquotes
272 and the parenthesized form
274 The only difference between these two forms is syntactic: it's easy to
275 make the parenthesized version nest, although that's not actually very
276 useful. The text between the backquotes or parentheses is broken into
277 words and executed as a command. It is not passed through the shell:
278 the author suspects that this would be too confusing. The standard
279 output of the command, with trailing newlines (but not internal or
280 leading newlines) removed, is the result of the substitution.
282 The \*(sw program, and this manual, are \*(mw productions, in association
283 with the European Bioinformatics Institute. They were written by Mark
284 Wooding <mdw@nsict.org>. Go and ask him if you have problems.