| 1 | .\" -*-nroff-*- |
| 2 | .\" |
| 3 | .\" $Id: sw-env.5,v 1.3 1999/07/30 18:44:32 mdw Exp $ |
| 4 | .\" |
| 5 | .\" Manual page for `sw-env' files |
| 6 | .\" |
| 7 | .\" (c) 1999 EBI |
| 8 | .\" |
| 9 | . |
| 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. |
| 27 | . |
| 28 | .\"----- Revision history --------------------------------------------------- |
| 29 | .\" |
| 30 | .\" $Log: sw-env.5,v $ |
| 31 | .\" Revision 1.3 1999/07/30 18:44:32 mdw |
| 32 | .\" Improve cross-references and tidy up formatting. |
| 33 | .\" |
| 34 | .\" Revision 1.2 1999/07/16 12:45:37 mdw |
| 35 | .\" Internal formatting improvements. |
| 36 | .\" |
| 37 | .\" Revision 1.1 1999/06/04 13:56:18 mdw |
| 38 | .\" New manual page. |
| 39 | .\" |
| 40 | . |
| 41 | .\" --- Useful macro definitions --- |
| 42 | . |
| 43 | .de VS \" Start a sort-of verbatim block |
| 44 | .sp 1 |
| 45 | .in +5n |
| 46 | .nf |
| 47 | .ft B |
| 48 | .. |
| 49 | .de VE \" Stop a sort-of verbatim block |
| 50 | .ft R |
| 51 | .fi |
| 52 | .in -5n |
| 53 | .sp 1 |
| 54 | .. |
| 55 | .de hP \" Start an indented paragraph with a bold right-aligned label |
| 56 | .IP |
| 57 | \fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c |
| 58 | .. |
| 59 | .\" |
| 60 | .\" --- Style hacking --- |
| 61 | .\" |
| 62 | .ie \n(.g \{\ |
| 63 | . fam P |
| 64 | . ds mw \fR[\f(BImdw\fR] |
| 65 | .\} |
| 66 | .el .ds mw \fR[\fBmdw\fR] |
| 67 | .ie t .ds o \(bu |
| 68 | .el .ds o o |
| 69 | .ds sw \fBsw\fP |
| 70 | .ds se \fBsw\-env\fP |
| 71 | . |
| 72 | .\"----- Main manual text --------------------------------------------------- |
| 73 | . |
| 74 | .TH sw-env 5 "25 May 1999" sw-tools |
| 75 | .PD 1 |
| 76 | . |
| 77 | .\"-------------------------------------------------------------------------- |
| 78 | . |
| 79 | .SH NAME |
| 80 | . |
| 81 | sw\-env \- environment variable assignment files for \*(sw. |
| 82 | . |
| 83 | .\"-------------------------------------------------------------------------- |
| 84 | . |
| 85 | .SH "DESCRIPTION" |
| 86 | . |
| 87 | A \*(se file is a sequence of statements. The following statements are |
| 88 | supported: |
| 89 | .sp 1 |
| 90 | .in +5n |
| 91 | .B : |
| 92 | .I value |
| 93 | .RB [ ; ] |
| 94 | .br |
| 95 | .B include |
| 96 | .I value |
| 97 | .RB [ ; ] |
| 98 | .br |
| 99 | .B arch |
| 100 | .I value |
| 101 | .B { |
| 102 | .IR statement ... |
| 103 | .B } |
| 104 | .RB [ ; ] |
| 105 | .br |
| 106 | .RB [ set ] |
| 107 | .I name |
| 108 | .RB [ = ] |
| 109 | .I value |
| 110 | .RB [ ; ] |
| 111 | .br |
| 112 | .B unset |
| 113 | .I name |
| 114 | .RB [ ; ] |
| 115 | .in -5n |
| 116 | .sp 1 |
| 117 | Whitespace serves to separate tokens but is otherwise ignored except |
| 118 | when it occurs quoted within a |
| 119 | .IR value . |
| 120 | The file may also contain comments, which begin with a |
| 121 | .RB ` # ' |
| 122 | character and extend to the end of the line. The start of a comment |
| 123 | must appear where a new statement is expected. Apart from its behaviour |
| 124 | of terminating comments, newlines behave the same way as other |
| 125 | whitespace characters. Keywords are not reserved words. |
| 126 | .PP |
| 127 | A |
| 128 | .I name |
| 129 | is a sequence of digits, letters and underscores which does not start |
| 130 | with a digit. |
| 131 | .PP |
| 132 | A |
| 133 | .I value |
| 134 | may contain any non-null character, although some characters are special |
| 135 | and must be quoted. The syntax of |
| 136 | .IR value s |
| 137 | is loosely based on the Bourne |
| 138 | shell, although there are differences and irregularities due to the |
| 139 | quick and dirty nature of the parser. The various quoting and |
| 140 | substitution operations are described below. |
| 141 | . |
| 142 | .SS "Statements" |
| 143 | . |
| 144 | The statements behave as follows: |
| 145 | .TP |
| 146 | .B : |
| 147 | The following |
| 148 | .I value |
| 149 | is read and discarded. This is not useless: reading a |
| 150 | .I value |
| 151 | may cause variables to be assigned as a result of |
| 152 | `\c |
| 153 | .BI ${ name = value }\c |
| 154 | \&' substitutions. |
| 155 | .TP |
| 156 | .B include |
| 157 | A |
| 158 | .I value |
| 159 | is read, and further assignments are read from the file so named, if it |
| 160 | exists. Conventionally, the last statement in the global \*(se file is |
| 161 | .VS |
| 162 | include ".sw-env"; |
| 163 | .VE |
| 164 | to read in package-specific settings. |
| 165 | .TP |
| 166 | .B arch |
| 167 | The following |
| 168 | .I value |
| 169 | is read. If it matches the name of the host's architecture, then the |
| 170 | brace-enclosed statements are executed; otherwise they're ignored. It's |
| 171 | possible, though not useful, to nest |
| 172 | .B arch |
| 173 | statements. |
| 174 | .TP |
| 175 | .B set |
| 176 | A |
| 177 | .I name |
| 178 | and |
| 179 | .I value |
| 180 | are read, optionally separated by an |
| 181 | .RB ` = ' |
| 182 | character. The variable named is assigned the value, replacing any |
| 183 | previously assigned value, if any. The |
| 184 | .RB ` set ' |
| 185 | keyword is optional. It's only useful so that you can assign values to |
| 186 | variables whose names are also statement keywords. |
| 187 | .TP |
| 188 | .B unset |
| 189 | A |
| 190 | .I name |
| 191 | is read. Any value assigned to the variable named is discarded, and the |
| 192 | variable is forgotten. |
| 193 | . |
| 194 | .SS "Value syntax" |
| 195 | . |
| 196 | The parser usually reads a |
| 197 | .I value |
| 198 | a character by character, until it finds a delimiter. Delimiter |
| 199 | characters are |
| 200 | .RB ` ( ', |
| 201 | .RB ` ) ', |
| 202 | .RB ` { ', |
| 203 | .RB ` } ', |
| 204 | and |
| 205 | .RB ` ; '; |
| 206 | whitespace also acts as a delimiter. Delimiter characters can only |
| 207 | appear in a value if quoted. |
| 208 | .PP |
| 209 | There are three types of quoting understood by the value reader. A |
| 210 | backslash |
| 211 | .RB (` \e ') |
| 212 | character causes the following character to be stripped of its special |
| 213 | meaning. Hence |
| 214 | .RB ` \e\e ' |
| 215 | inserts a literal backslash. Text between single quotes |
| 216 | .RB ` \' ... \' ' |
| 217 | is read |
| 218 | entirely as-is, including all whitespace, newlines, backslashes, |
| 219 | everything. To include a single quote in a piece of single-quoted text, |
| 220 | use the sequence |
| 221 | .RB ` \'\e\'\' ', |
| 222 | as in the shell. (This drops out of single-quoting, inserts an escaped |
| 223 | single quote, and resumes quoting.) Text between double quotes |
| 224 | .BR """" ... """" |
| 225 | is partially quoted: delimiters and whitespace are read as normal |
| 226 | characters, but substitutions using the |
| 227 | .RB ` $ ' |
| 228 | and |
| 229 | .RB ` \` ' |
| 230 | characters are still made, and the backslash retains its behaviour of |
| 231 | escaping the following character. |
| 232 | .PP |
| 233 | Two sorts of substitutions are available in values: |
| 234 | .I "variable substitution" |
| 235 | examines a variable and substitutes some text based on its value, and |
| 236 | .I "command substitution" |
| 237 | runs a command and substitutes its output. |
| 238 | .PP |
| 239 | The simplest variable substitution takes the form |
| 240 | .RB ` $\c |
| 241 | .IR name ': |
| 242 | this is replaced by the value of the variable called |
| 243 | .IR name , |
| 244 | or the empty string if there is no such variable defined. The name may |
| 245 | be enclosed in braces should it be necessary to clearly disambiguate the |
| 246 | end of the name. |
| 247 | .PP |
| 248 | More complex variable substitutions are permitted: |
| 249 | .TP |
| 250 | .BI ${ name \- text } |
| 251 | Expands to the value of the variable called |
| 252 | .I name |
| 253 | if it's defined, or |
| 254 | .I text |
| 255 | if not. |
| 256 | .TP |
| 257 | .BI ${ name + text } |
| 258 | Expands to |
| 259 | .I text |
| 260 | if there is a variable called |
| 261 | .I name |
| 262 | defined, or nothing. |
| 263 | .TP |
| 264 | .BI ${ name = text } |
| 265 | If there is no variable called |
| 266 | .I name |
| 267 | then create one with the value |
| 268 | .IR text ; |
| 269 | then expands to the variable's value. |
| 270 | .PP |
| 271 | In each of the above, prefixing the operator character |
| 272 | .RB ` \- ', |
| 273 | .RB ` + ' |
| 274 | or |
| 275 | .RB ` = ' |
| 276 | with a colon |
| 277 | .RB (` : ') |
| 278 | changes the variable existence test, such that it will believe that a |
| 279 | variable whose value is the empty string is not defined. Each |
| 280 | .I text |
| 281 | part in the above forms is syntactically a |
| 282 | .IR value , |
| 283 | and may itself contain quoting and substitutions. It may also contain |
| 284 | unescaped whitespace. |
| 285 | .PP |
| 286 | There are two forms for command substitution: the backtick form, where a |
| 287 | command is enclosed in backquotes |
| 288 | .RB ` \` ... \` '; |
| 289 | and the parenthesized form |
| 290 | .RB ` $( ... ) '. |
| 291 | The only difference between these two forms is syntactic: it's easy to |
| 292 | make the parenthesized version nest, although that's not actually very |
| 293 | useful. The text between the backquotes or parentheses is broken into |
| 294 | words and executed as a command. It is not passed through the shell: |
| 295 | the author suspects that this would be too confusing. The standard |
| 296 | output of the command, with trailing newlines (but not internal or |
| 297 | leading newlines) removed, is the result of the substitution. |
| 298 | . |
| 299 | .\"-------------------------------------------------------------------------- |
| 300 | . |
| 301 | .SH "AUTHOR" |
| 302 | . |
| 303 | The \*(sw program, and this manual, are \*(mw productions, in association |
| 304 | with the European Bioinformatics Institute. They were written by Mark |
| 305 | Wooding <mdw@nsict.org>. Go and ask him if you have problems. |
| 306 | . |
| 307 | .\"----- That's all, folks -------------------------------------------------- |