mdw@git.distorted.org.uk Git - sw-tools/blob - sw-env.5

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