.\" -*-nroff-*-
.\"
-.\" $Id: sw-env.5,v 1.3 1999/07/30 18:44:32 mdw Exp $
+.\" $Id: sw-env.5,v 1.4 2004/04/08 01:52:18 mdw Exp $
.\"
.\" Manual page for `sw-env' files
.\"
.\" 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 --------------------------------------------------
~mdw / sw-tools / blobdiff