.\" -*-nroff-*-
.\"
.\" Manual for `runlisp' configuration files
.\"
.\" (c) 2020 Mark Wooding
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of Runlisp, a tool for invoking Common Lisp scripts.
.\"
.\" Runlisp 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 3 of the License, or (at your
.\" option) any later version.
.\"
.\" Runlisp 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 Runlisp.  If not, see <https://www.gnu.org/licenses/>.
.
.ie t \{\
.  ds o \(bu
.  if \n(.g \{\
.    fam P
.    ev an-1
.    fam P
.    ev
.  \}
.\}
.el \{\
.  ds o o
.\}
.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.ds , \h'.16667m'
.
.\"--------------------------------------------------------------------------
.TH runlisp.conf 5 "27 August 2020" "Mark Wooding"
.SH NAME
runlisp.conf \- configuration files for runlisp
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
.
.SS "General syntax"
In summary,
a configuration file is structured as a collection of assignments
.I variable
.B =
.IR value ,
gathered into named sections by header lines
.BI [ section ]\fR.
.PP
Comments are indicated by a semicolon
.RB ` ; '
in the leftmost column,
and extend to the end of the line;
comments and lines consisting only of whiteapace are ignored
and have no effect whatever.
Semicolons not in the first column do
.I not
introduce comments,
and have no special meaning.
.PP
A
.I name
is a non-empty sequence of ASCII alphanumeric characters,
or the special constituent characters
.RB ` \- ',
.RB ` _ ',
.RB ` . ',
.RB ` / ',
.RB ` * ',
.RB ` + ',
.RB ` *% ',
or
.RB ` @ '.
For example,
.RB ` foo ',
.RB ` 12345 ',
.RB ` \-2.718 ',
.RB ` 113/355 ',
.RB ` image-dir ',
.RB ` @%IMAGEDIR ',
and
.RB ` *organa-solo* '
are all names, but
.RB ` foo:bar '
.RB ` happy? '
and
.RB ` $3.95 '
are not.
Names beginning with
.RB ` @ '
are reserved for use by the
.B runlisp
programs;
names beginning with
.RB ` % '
or
.RB ` @% '
are by convention private.
.PP
A
.I section header
is a line of the form
.IP
.BI [ section ]
.PP
where
.I section
is a name, as defined above.
There may be whitespace before and after the
.I name
or after the
.RB  ` ] '.
Section headers need not have distinct names.
Subsequent assignments are applied to the section called
.IR name ,
up until the next section header, or the end of the file.
Assignments prior to the first section header in a file
are applied to the
.B @CONFIG
section.
.PP
An
.I assignment
begins with a line of the form
.IP
.I variable
.B =
.I rest
.PP
where
.I variable
is a name, as defined above,
and it includes all subsequent
(non-empty, non-comment)
lines up to, but not including,
the next line which does
.I not
begin with whitespace or a semicolon,
or the end of the input file.
There may be space before or after the
.RB ` = '.
The
.I value
assigned consists of the text of the initial line following the
.RB ` = '
character
(shown as
.I rest
above),
together with the contents of the subsequent lines;
initial and trailing whitespace is removed from each piece,
and the (nonempty) pieces are joined,
separated by single spaces.
We say that a assignment
assigns a value to the variable
in some section \(en
namely, the section in which the assignment is applied.
.PP
For example,
consider the following file.
.IP
.ft B
.nf
long =
	one

	two
; this line is a comment
	; not a comment
	three

short = just a quick note
.fi
.ft P
.PP
Then
.B long
is assigned the value
.RB ` "one two ; not a comment three" ',
and
.B short is assigned
.RB ` "just a quick note" '.
.PP
The assignments applied to a section
need not have distinct variable names.
Only the last assignment to a particular variable name in a section is
.IR effective ;
the earlier assignments are simply ignored.
If an effective assignment assigns a value to a variable in a section,
we say that the variable is
.I set
to that value in the section.
.
.SS "Lookup and inheritance"
A section may have zero or more
.I parent
sections.
.PP
The
.BR @BUILTIN ,
.BR @CONFIG ,
and
.B @ENV
sections have no parents.
The
.B @CONFIG
section has one parent, namely
.BR @BUILTIN .
.PP
If the variable
.B @parents
is set in a section other than one of those named above,
then it must consist of a space- or comma-separated list
of names,
which name the section's parents.
Currently, the parents need not be distinct,
though duplicates have no effect other than slowing down lookup.
The order in which parents are listed is not significant.
If
.B @parents
is not set in a section other than one of those named above,
then by default it has one parent, namely
.BR @COMMON .
.PP
It is currently possible to build a cyclic structure of parent links.
This is not recommended.
If lookup (explained below) detects a cycle
then it will report a fatal error,
but cycles may exist without being detected.
.PP
A variable is
.I "looked up"
in a section as follows.
.hP 1.
If there is an effective assignment
of a value to that variable in the section
then lookup finds that assignment.
.hP 2.
If the section has no parents,
then lookup fails.
.hP 3.
Otherwise, the variable is looked up in each of the section's parents.
If none of these lookups succeeds, then the lookup fails.
If all of the successful lookups found the
.I "same assignment"
(not just the same value!)
then lookup finds that assignment.
Otherwise, the lookup reports an error.
.
.SS "Expansion and word-splitting"
A value can be
.I expanded
relative to some home section,
and optionally split into words.
.PP
Not all values are
.IR expandable .
Values set by assignments in a configuration file are always expandable.
Values set on the command line \(en in
.B \-o
options \(en are not expandable.
Values in the
.B @ENV
section from environment variables (see below) are not expandable.
Some values set in the
.B @BUILTIN
section are expandable and some are not.
Applying expansion to a value that is not expandable
simply results in that same value, unchanged.
.PP
Applying expansion to an expandable value
produces a result string as follows.
The value is scanned from start to end.
.hP \*o
A backslash
.RB ` \e '
is discarded, but the immediately following character
is copied to the output without further inspection.
.hP \*o
A
.I variable substitution
takes the form
.BR ${ [ \c
.IB sect : \c
.RI ] var \c
.RB [ | \c
.IR filter ]... \c
.RB [ ? \c
.IR alt ] \c
.BR } .
A variable named
.I var
is looked up in the section named
.IR sect ,
or, if omitted, in the home section.
If the lookup succeeds,
then the value is expanded,
processed by the
.IR filter s
(explained below),
and appended to the output.
If the lookup failed,
and
.BI ? alt
is present,
then
.I alt
is expanded and appended to the output.
Otherwise,
if the lookup fails and there is no
.I alt
text, then an error is reported.
.IP
A filter
.B u
causes the expanded value to be converted to uppercase;
similarly,
.B l
causes the expanded value to be converted to lowercase.
A filter
.B q
causes a backslash to be inserted before each
backslash or double-quote character in the expanded value,
so that this can be used as part of a quoted Common Lisp string.
.hP \*o
A
.I conditional
takes the form
.BR $? [ \c
.IB sect : \c
.RI ] var \c
.BI { conseq \c
.RB [ | \c
.IR alt ] \c
.BR } .
A variable named
.I var
is looked up in the section named
.IR sect ,
or, if omitted, in the home section.
If the lookup succeeds, then
.I conseq
is expanded and appended to the output;
otherwise, if
.I alt
is present, then it is expanded and appended to the output;
otherwise, nothing happens.
.hP \*o
A dollar sign which doesn't introduce one of the forms above
is invalid, and a fatal error is reported.
.hP \*o
Any other characters are simply appended to the output.
.PP
Word-splitting is similar but more complex.
The result is not a string, but a sequence of strings.
At any given point in this procedure,
there may be a partially constructed word,
or there might not.
.hP \*o
Outside of quotes (see below),
whitespace serves to separate words.
When a whitespace character is encountered,
if there is a word under construction,
then it is finished and added to the output list;
otherwise it is simply ignored.
.hP \*o
If a backslash is encountered,
then a word is started if there is none currently under construction,
and the character following the backslash is added to the current word.
.hP \*o
If a single-quote character
.RB ` ' '
is encountered,
then a word is started if there is none currently under construction,
and
.I all
characters up to the next single quote
are added to the current word.
This includes double quotes, dollar signs, and backslashes.
(Neither of the two single quotes is appended to the current word.)
.hP \*o
If a double-quote character
.RB ` """" '
is encountered,
then a word is started if there is none currently under construction.
Until the next double quote is encountered,
whitespace and single quotes treated literally,
and simply added to the current word;
backslashes can be used to escape characters,
such as double quotes,
as usual.
.hP \*o
If a
.BR $ -expansion
\(en a variable substitution or conditional (as described above) \(en
is encountered
and there is a current word under construction,
then the result of the
.BR $ -expansion
is appended to the current word.
If there is no current word,
then the variable value, or consequent or alternative text,
is subjected to word splitting in addition to expansion,
and the resulting words appended to the output sequence.
.hP \*o
If any other character is encountered,
then a word is started if there is none currently under construction,
and the character is appended to the current word.
.PP
One case which deserves attention:
if a
.BR $ -expansion
is encountered outside of a word,
so that the result is subject to word splitting,
then an error is reported if a new word is started
without there being whitespace between the closing brace of the
.B $ -expansion
and the character which started the new word.
For example,
.IP
.B "bad = one ${x}two"
.PP
would be invalid in a word-splitting context.
.
.SS "Predefined variables in @BUILTIN"
The
.B @BULITIN
Section has no parents.
You should not override its settings in configuration files.
it holds a number of variables set by the
.B runlisp
programs.
.TP
.B @data-dir
The directory in which
.BR runlisp 's
auxiliary data files and scripts are located.
This is determined by the
.B RUNLISP_DATADIR
environment variable,
the
.B data-dir
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.TP
.B @ecl-opt
The preferred option prefix for ECL, either
.RB ` \- '
or
.RB ` \-\- '.
(For some reason,
the ECL developers are changing
the way ECL recognizes command-line options,
because they think that the minor aesthetic improvement
is worth breaking everyone's scripts.)
This is determined by the
.B ecl-opt
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.TP
.B @image-dir
The directory in which
.B runlisp
looks for, and
.B dump-runlisp-image
stores, custom Lisp images.
This is determined by the
.B RUNLISP_IMAGEDIR
environment variable,
the
.B image-dir
variable in the
.B @CONFIG
section,
or a value determined at compile time.
.TP
.B @image-new
Set by
.BR dump-runlisp-image (1)
to the filename that a
.B dump-image
command should create.
.RB ( dump-runlisp-image
will rename the image into place itself,
if the command completes successfully.)
.TP
.B @image-out
Set by
.BR dump-runlisp-image (1)
to the filename of the intended output image.
(Don't use this in
.B dump-image
commands: use
.B @image-new
instread.)
.TP
.B @script
Set by
.BR runlisp (1)
to the name of the script being invoked.
.TP
.B @tmp-dir
Set by
.BR dump-runlisp-image (1)
to be the name of a directory in which a
.B dump-image
command can put temporary files.
.
.SS "Other special variables"
In every section, the section's name
is automatically assigned to the variable
.BR @name .
This variable
.I can
be overridden by an explicit assignment,
but this is not recommended.
.
.\"--------------------------------------------------------------------------
.
.SH BUGS
.hP \*o
.
.SH SEE ALSO
.BR dump-runlisp-image (1),
.BR query-runlisp-config (1),
.BR runlisp (1).
.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>
.
.\"----- That's all, folks --------------------------------------------------