e45f5509 |
1 | .\" -*-nroff-*- |
2 | .\" |
be07bee0 |
3 | .\" $Id: sw-env.5,v 1.2 1999/07/16 12:45:37 mdw Exp $ |
e45f5509 |
4 | .\" |
5 | .\" Manual page for `sw-env' files |
6 | .\" |
7 | .\" (c) 1999 EBI |
8 | .\" |
be07bee0 |
9 | . |
e45f5509 |
10 | .\"----- Licensing notice --------------------------------------------------- |
11 | .\" |
12 | .\" This file is part of sw-tools. |
13 | .\" |
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. |
18 | .\" |
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. |
23 | .\" |
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. |
be07bee0 |
27 | . |
e45f5509 |
28 | .\"----- Revision history --------------------------------------------------- |
29 | .\" |
30 | .\" $Log: sw-env.5,v $ |
be07bee0 |
31 | .\" Revision 1.2 1999/07/16 12:45:37 mdw |
32 | .\" Internal formatting improvements. |
33 | .\" |
e45f5509 |
34 | .\" Revision 1.1 1999/06/04 13:56:18 mdw |
35 | .\" New manual page. |
36 | .\" |
be07bee0 |
37 | . |
e45f5509 |
38 | .\" --- Useful macro definitions --- |
be07bee0 |
39 | . |
e45f5509 |
40 | .de VS \" Start a sort-of verbatim block |
41 | .sp 1 |
42 | .in +5n |
43 | .nf |
44 | .ft B |
45 | .. |
46 | .de VE \" Stop a sort-of verbatim block |
47 | .ft R |
48 | .fi |
49 | .in -5n |
50 | .sp 1 |
51 | .. |
be07bee0 |
52 | .de hP \" Start an indented paragraph with a bold right-aligned label |
e45f5509 |
53 | .IP |
54 | \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c |
55 | .. |
56 | .\" |
57 | .\" --- Style hacking --- |
58 | .\" |
59 | .ie \n(.g \{\ |
be07bee0 |
60 | . fam P |
61 | . ds mw \fR[\f(BImdw\fR] |
e45f5509 |
62 | .\} |
be07bee0 |
63 | .el .ds mw \fR[\fBmdw\fR] |
64 | .ie t .ds o \(bu |
65 | .el .ds o o |
e45f5509 |
66 | .ds sw \fBsw\fP |
67 | .ds se \fBsw\-env\fP |
be07bee0 |
68 | . |
69 | .\"----- Main manual text --------------------------------------------------- |
70 | . |
e45f5509 |
71 | .TH sw 1 "25 May 1999" "EBI tools" |
72 | .PD 1 |
be07bee0 |
73 | . |
74 | .\"-------------------------------------------------------------------------- |
75 | . |
e45f5509 |
76 | .SH NAME |
be07bee0 |
77 | . |
e45f5509 |
78 | sw\-env \- environment variable assignment files for \*(sw. |
be07bee0 |
79 | . |
80 | .\"-------------------------------------------------------------------------- |
81 | . |
e45f5509 |
82 | .SH DESCRIPTION |
be07bee0 |
83 | . |
e45f5509 |
84 | A \*(se file is a sequence of statements. The following statements are |
85 | supported: |
86 | .sp 1 |
87 | .in +5n |
88 | .B : |
89 | .I value |
90 | .RB [ ; ] |
91 | .br |
92 | .B include |
93 | .I value |
94 | .RB [ ; ] |
95 | .br |
96 | .B arch |
97 | .I value |
98 | .B { |
99 | .IR statement ... |
100 | .B } |
101 | .RB [ ; ] |
102 | .br |
103 | .RB [ set ] |
104 | .I name |
105 | .RB [ = ] |
106 | .I value |
107 | .RB [ ; ] |
108 | .br |
109 | .B unset |
110 | .I name |
111 | .RB [ ; ] |
112 | .in -5n |
113 | .sp 1 |
114 | Whitespace serves to separate tokens but is otherwise ignored except |
115 | when it occurs quoted within a |
116 | .IR value . |
117 | The file may also contain comments, which begin with a |
118 | .RB ` # ' |
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. |
123 | .PP |
124 | A |
125 | .I name |
126 | is a sequence of digits, letters and underscores which does not start |
127 | with a digit. |
128 | .PP |
129 | A |
130 | .I value |
131 | may contain any non-null character, although some characters are special |
132 | and must be quoted. The syntax of |
133 | .IR value s |
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. |
be07bee0 |
138 | . |
e45f5509 |
139 | .SS "Statements" |
be07bee0 |
140 | . |
e45f5509 |
141 | The statements behave as follows: |
142 | .TP |
143 | .B : |
144 | The following |
145 | .I value |
146 | is read and discarded. This is not useless: reading a |
147 | .I value |
148 | may cause variables to be assigned as a result of |
149 | `\c |
150 | .BI ${ name = value }\c |
151 | \&' substitutions. |
152 | .TP |
153 | .B include |
154 | A |
155 | .I value |
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 |
158 | .VS |
159 | include ".sw-env"; |
160 | .VE |
161 | to read in package-specific settings. |
162 | .TP |
163 | .B arch |
164 | The following |
165 | .I value |
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 |
169 | .B arch |
170 | statements. |
171 | .TP |
172 | .B set |
173 | A |
174 | .I name |
175 | and |
176 | .I value |
177 | are read, optionally separated by an |
178 | .RB ` = ' |
179 | character. The variable named is assigned the value, replacing any |
180 | previously assigned value, if any. The |
181 | .RB ` set ' |
182 | keyword is optional. It's only useful so that you can assign values to |
183 | variables whose names are also statement keywords. |
184 | .TP |
185 | .B unset |
186 | A |
187 | .I name |
188 | is read. Any value assigned to the variable named is discarded, and the |
189 | variable is forgotten. |
be07bee0 |
190 | . |
e45f5509 |
191 | .SS "Value syntax" |
be07bee0 |
192 | . |
e45f5509 |
193 | The parser usually reads a |
194 | .I value |
195 | a character by character, until it finds a delimiter. Delimiter |
196 | characters are |
197 | .RB ` ( ', |
198 | .RB ` ) ', |
199 | .RB ` { ', |
200 | .RB ` } ', |
201 | and |
202 | .RB ` ; '; |
203 | whitespace also acts as a delimiter. Delimiter characters can only |
204 | appear in a value if quoted. |
205 | .PP |
206 | There are three types of quoting understood by the value reader. A |
207 | backslash |
208 | .RB (` \e ') |
209 | character causes the following character to be stripped of its special |
210 | meaning. Hence |
211 | .RB ` \e\e ' |
212 | inserts a literal backslash. Text between single quotes |
213 | .RB ` \' ... \' ' |
214 | is read |
215 | entirely as-is, including all whitespace, newlines, backslashes, |
216 | everything. To include a single quote in a piece of single-quoted text, |
217 | use the sequence |
218 | .RB ` \'\e\'\' ', |
219 | as in the shell. (This drops out of single-quoting, inserts an escaped |
220 | single quote, and resumes quoting.) Text between double quotes |
221 | .BR """" ... """" |
222 | is partially quoted: delimiters and whitespace are read as normal |
223 | characters, but substitutions using the |
224 | .RB ` $ ' |
225 | and |
226 | .RB ` \` ' |
227 | characters are still made, and the backslash retains its behaviour of |
228 | escaping the following character. |
229 | .PP |
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. |
235 | .PP |
236 | The simplest variable substitution takes the form |
237 | .RB ` $\c |
238 | .IR name ': |
239 | this is replaced by the value of the variable called |
240 | .IR name , |
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 |
243 | end of the name. |
244 | .PP |
245 | More complex variable substitutions are permitted: |
246 | .TP |
247 | .BI ${ name \- text } |
248 | Expands to the value of the variable called |
249 | .I name |
250 | if it's defined, or |
251 | .I text |
252 | if not. |
253 | .TP |
254 | .BI ${ name + text } |
255 | Expands to |
256 | .I text |
257 | if there is a variable called |
258 | .I name |
259 | defined, or nothing. |
260 | .TP |
261 | .BI ${ name = text } |
262 | If there is no variable called |
263 | .I name |
264 | then create one with the value |
265 | .IR text ; |
266 | then expands to the variable's value. |
267 | .PP |
268 | In each of the above, prefixing the operator character |
269 | .RB ` \- ', |
270 | .RB ` + ' |
271 | or |
272 | .RB ` = ' |
273 | with a colon |
274 | .RB (` : ') |
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 |
277 | .I text |
278 | part in the above forms is syntactically a |
279 | .IR value , |
280 | and may itself contain quoting and substitutions. It may also contain |
281 | unescaped whitespace. |
282 | .PP |
283 | There are two forms for command substitution: the backtick form, where a |
284 | command is enclosed in backquotes |
285 | .RB ` \` ... \` '; |
286 | and the parenthesized form |
287 | .RB ` $( ... ) '. |
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. |
be07bee0 |
295 | . |
296 | .\"-------------------------------------------------------------------------- |
297 | . |
e45f5509 |
298 | .SH AUTHOR |
be07bee0 |
299 | . |
e45f5509 |
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. |
be07bee0 |
303 | . |
304 | .\"----- That's all, folks -------------------------------------------------- |