Improve cross-references and tidy up formatting.

[sw-tools] / sw-env.5

.\" -*-nroff-*-
.\"
.\" $Id: sw-env.5,v 1.3 1999/07/30 18:44:32 mdw Exp $
.\"
.\" Manual page for `sw-env' files
.\"
.\" (c) 1999 EBI
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of sw-tools.
.\"
.\" sw-tools is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" (at your option) any later version.
.\" 
.\" sw-tools is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\" 
.\" You should have received a copy of the GNU General Public License
.\" along with sw-tools; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
.\"----- Revision history ---------------------------------------------------
.\"
.\" $Log: sw-env.5,v $
.\" Revision 1.3  1999/07/30 18:44:32  mdw
.\" Improve cross-references and tidy up formatting.
.\"
.\" Revision 1.2  1999/07/16 12:45:37  mdw
.\" Internal formatting improvements.
.\"
.\" Revision 1.1  1999/06/04 13:56:18  mdw
.\" New manual page.
.\"
.
.\" --- Useful macro definitions ---
.
.de VS \" Start a sort-of verbatim block
.sp 1
.in +5n
.nf
.ft B
..
.de VE \" Stop a sort-of verbatim block
.ft R
.fi
.in -5n
.sp 1
..
.de hP \" Start an indented paragraph with a bold right-aligned label
.IP
\fB\h'-\w'\\$1\ 'u'\\$1\ \fP\c
..
.\"
.\" --- Style hacking ---
.\"
.ie \n(.g \{\
.  fam P
.  ds mw \fR[\f(BImdw\fR]
.\}
.el .ds mw \fR[\fBmdw\fR]
.ie t .ds o \(bu
.el .ds o o
.ds sw \fBsw\fP
.ds se \fBsw\-env\fP
.
.\"----- Main manual text ---------------------------------------------------
.
.TH sw-env 5 "25 May 1999" sw-tools
.PD 1
.
.\"--------------------------------------------------------------------------
.
.SH NAME
.
sw\-env \- environment variable assignment files for \*(sw.
.
.\"--------------------------------------------------------------------------
.
.SH "DESCRIPTION"
.
A \*(se file is a sequence of statements.  The following statements are
supported:
.sp 1
.in +5n
.B :
.I value
.RB [ ; ]
.br
.B include
.I value
.RB [ ; ]
.br
.B arch
.I value
.B {
.IR statement ...
.B }
.RB [ ; ]
.br
.RB [ set ]
.I name
.RB [ = ]
.I value
.RB [ ; ]
.br
.B unset
.I name
.RB [ ; ]
.in -5n
.sp 1
Whitespace serves to separate tokens but is otherwise ignored except
when it occurs quoted within a
.IR value .
The file may also contain comments, which begin with a
.RB ` # '
character and extend to the end of the line.  The start of a comment
must appear where a new statement is expected.  Apart from its behaviour
of terminating comments, newlines behave the same way as other
whitespace characters.  Keywords are not reserved words.
.PP
A
.I name
is a sequence of digits, letters and underscores which does not start
with a digit.
.PP
A
.I value
may contain any non-null character, although some characters are special
and must be quoted.  The syntax of
.IR value s
is loosely based on the Bourne
shell, although there are differences and irregularities due to the
quick and dirty nature of the parser.  The various quoting and
substitution operations are described below.
.
.SS "Statements"
.
The statements behave as follows:
.TP
.B :
The following
.I value
is read and discarded.  This is not useless: reading a
.I value
may cause variables to be assigned as a result of
`\c
.BI ${ name = value }\c
\&' substitutions.
.TP
.B include
A
.I value
is read, and further assignments are read from the file so named, if it
exists.  Conventionally, the last statement in the global \*(se file is
.VS
include ".sw-env";
.VE
to read in package-specific settings.
.TP
.B arch
The following
.I value
is read.  If it matches the name of the host's architecture, then the
brace-enclosed statements are executed; otherwise they're ignored.  It's
possible, though not useful, to nest
.B arch
statements.
.TP
.B set
A
.I name
and
.I value
are read, optionally separated by an
.RB ` = '
character.  The variable named is assigned the value, replacing any
previously assigned value, if any.  The
.RB ` set '
keyword is optional.  It's only useful so that you can assign values to
variables whose names are also statement keywords.
.TP
.B unset
A
.I name
is read.  Any value assigned to the variable named is discarded, and the
variable is forgotten.
.
.SS "Value syntax"
.
The parser usually reads a
.I value
a character by character, until it finds a delimiter.  Delimiter
characters are
.RB ` ( ',
.RB ` ) ',
.RB ` { ',
.RB ` } ',
and
.RB ` ; ';
whitespace also acts as a delimiter.  Delimiter characters can only
appear in a value if quoted.
.PP
There are three types of quoting understood by the value reader.  A
backslash
.RB (` \e ')
character causes the following character to be stripped of its special
meaning.  Hence
.RB ` \e\e '
inserts a literal backslash.  Text between single quotes
.RB ` \' ... \' '
is read
entirely as-is, including all whitespace, newlines, backslashes,
everything.  To include a single quote in a piece of single-quoted text,
use the sequence
.RB ` \'\e\'\' ',
as in the shell.  (This drops out of single-quoting, inserts an escaped
single quote, and resumes quoting.)  Text between double quotes
.BR """" ... """"
is partially quoted: delimiters and whitespace are read as normal
characters, but substitutions using the
.RB ` $ '
and
.RB ` \` '
characters are still made, and the backslash retains its behaviour of
escaping the following character.
.PP
Two sorts of substitutions are available in values:
.I "variable substitution"
examines a variable and substitutes some text based on its value, and
.I "command substitution"
runs a command and substitutes its output.
.PP
The simplest variable substitution takes the form
.RB ` $\c
.IR name ':
this is replaced by the value of the variable called
.IR name ,
or the empty string if there is no such variable defined.  The name may
be enclosed in braces should it be necessary to clearly disambiguate the
end of the name.
.PP
More complex variable substitutions are permitted:
.TP
.BI ${ name \- text }
Expands to the value of the variable called
.I name
if it's defined, or
.I text
if not.
.TP
.BI ${ name + text }
Expands to
.I text
if there is a variable called
.I name
defined, or nothing.
.TP
.BI ${ name = text }
If there is no variable called
.I name
then create one with the value
.IR text ;
then expands to the variable's value.
.PP
In each of the above, prefixing the operator character
.RB ` \- ',
.RB ` + '
or
.RB ` = '
with a colon
.RB (` : ')
changes the variable existence test, such that it will believe that a
variable whose value is the empty string is not defined.  Each
.I text
part in the above forms is syntactically a
.IR value ,
and may itself contain quoting and substitutions.  It may also contain
unescaped whitespace.
.PP
There are two forms for command substitution: the backtick form, where a
command is enclosed in backquotes
.RB ` \` ... \` ';
and the parenthesized form
.RB ` $( ... ) '.
The only difference between these two forms is syntactic: it's easy to
make the parenthesized version nest, although that's not actually very
useful.  The text between the backquotes or parentheses is broken into
words and executed as a command.  It is not passed through the shell:
the author suspects that this would be too confusing.  The standard
output of the command, with trailing newlines (but not internal or
leading newlines) removed, is the result of the substitution.
.
.\"--------------------------------------------------------------------------
.
.SH "AUTHOR"
.
The \*(sw program, and this manual, are \*(mw productions, in association
with the European Bioinformatics Institute.  They were written by Mark
Wooding <mdw@nsict.org>.  Go and ask him if you have problems.
.
.\"----- That's all, folks --------------------------------------------------