aboutsummaryrefslogtreecommitdiff
path: root/doc/argot_config.5
diff options
context:
space:
mode:
Diffstat (limited to 'doc/argot_config.5')
-rw-r--r--doc/argot_config.5352
1 files changed, 352 insertions, 0 deletions
diff --git a/doc/argot_config.5 b/doc/argot_config.5
new file mode 100644
index 0000000..abd6420
--- /dev/null
+++ b/doc/argot_config.5
@@ -0,0 +1,352 @@
1.\" This file is part of argot -*- nroff -*-
2.\" Copyright (C) 2007-2016 Sergey Poznyakoff
3.\"
4.\" Grecs is free software; you can redistribute it and/or modify
5.\" it under the terms of the GNU General Public License as published by
6.\" the Free Software Foundation; either version 3, or (at your option)
7.\" any later version.
8.\"
9.\" Grecs is distributed in the hope that it will be useful,
10.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
11.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12.\" GNU General Public License for more details.
13.\"
14.\" You should have received a copy of the GNU General Public License
15.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
16.\"
17.TH ARGOT_CONFIG 3 "December 25, 2014" "ARGOT" "Grecs User Reference"
18.SH NAME
19\fBGrecs\fR configuration file syntax
20.SH DESCRIPTION
21.PP
22A configuration file consists of statements and comments.
23.PP
24There are three classes of lexical tokens: keywords, values, and
25separators. Blanks, tabs, newlines and comments, collectively called
26\fIwhite space\fR are ignored except as they serve to separate
27tokens. Some white space is required to separate otherwise adjacent
28keywords and values.
29.SH COMMENTS
30Comments may appear anywhere where white space may appear in the
31configuration file. There are two kinds of comments:
32single-line and multi-line comments. Single-line comments start
33with
34.B #
35or
36.B //
37and continue to the end of the line:
38.sp
39.RS 4
40.nf
41# This is a comment
42// This too is a comment
43.fi
44.RE
45.PP
46\fIMulti-line\fB or \fIC-style\fB comments start with the two
47characters
48.B /*
49(slash, star) and continue until the first occurrence of
50.B */
51(star, slash).
52.PP
53Multi-line comments cannot be nested. However, single-line comments
54may well appear within multi-line ones.
55.SS "Pragmatic Comments"
56Pragmatic comments are similar to usual single-line comments,
57except that they cause some changes in the way the configuration is
58parsed. Pragmatic comments begin with a
59.B #
60sign and end with the next physical newline character.
61.TP
62.BR "#include <" "file" >
63.PD 0
64.TP
65.BR "#include " "file"
66.PD
67Include the contents of the file \fIfile\fR. There are three possible
68use cases.
69
70If \fIfile\fR is an absolute file name, the named file is included.
71An error message will be issued if it does not exist.
72
73If \fIfile\fR contains wildcard characters (\fB*\fR, \fB[\fR,
74\fB]\fR or \fB?\fR), it is interpreted as shell globbing pattern and
75all files matching that pattern are included, in lexicographical
76order. If no files match the pattern, the statement is silently
77ignored.
78
79Otherwise, the form with angle brackets searches for file in the
80\fIinclude search path\fR, while the second one looks for it in the
81current working directory first, and, if not found there, in the
82include search path. If the file is not found, an error message will
83be issued.
84.sp
85The default include search path is:
86.sp
87\fIprefix\fR/share/\fIPROGNAME\fR/\fIVERSION\fR/include
88.br
89\fIprefix\fR/share/\fIPROGNAME\fR/include
90.sp
91where \fIprefix\fR stands for the installation prefix (normally
92\fB/usr\fR or \fB/usr/local\fR), \fIPROGNAME\fR stands for the name of
93the program which uses the configuration file, and \fIVERSION\fR for
94its version number.
95.sp
96The include search path can be modified using the
97.BI argot_include_path_setup ()
98and
99.BI argot_include_path_setup_v ()
100functions. Refer to
101.BR argot_include_path_setup (3),
102for a detailed discussion.
103.TP
104.BR "#include_once <" "file" >
105.PD 0
106.TP
107.BR "#include_once " "file"
108.PD
109Same as \fB#include\fR, except that, if the \fIfile\fR has already
110been included, it will not be included again.
111.TP
112.BR "#line " "num"
113.PD 0
114.TP
115.BR "#line " "num" " \(dq" "file" "\(dq"
116.PD
117This line causes the parser to believe, for purposes of error
118diagnostics, that the line number of the next source line
119is given by \fInum\fR and the current input file is named by
120\fIfile\fR. If the latter is absent, the remembered file name
121does not change.
122.TP
123.BR "# " "num" " \(dq" "file" "\(dq"
124This is a special form of the \fB#line\fR statement, understood for
125compatibility with the C preprocessor.
126.PP
127These statements provide a rudimentary preprocessing
128features. For more sophisticated ways to modify configuration before
129parsing, see \fBPREPROCESSOR\fR.
130.SH STATEMENTS
131.SS "Simple statement"
132A \fIsimple statement\fR consists of a keyword and value
133separated by any amount of whitespace. Simple statement is terminated
134with a semicolon (\fB;\fR).
135.PP
136The following is a simple statement:
137.sp
138.RS 4
139.nf
140standalone yes;
141pidfile /var/run/slb.pid;
142.RE
143.fi
144.PP
145A \fIkeyword\fR begins with a letter and may contain letters,
146decimal digits, underscores (\fB_\fR) and dashes (\fB-\fR).
147Examples of keywords are:
148.sp
149.RS 4
150.nf
151expression
152output-file
153.RE
154.fi
155.PP
156A \fIvalue\fR can be one of the following:
157.TP
158.I number
159A number is a sequence of decimal digits.
160.TP
161.I boolean
162A boolean value is one of the following: \fByes\fR, \fBtrue\fR,
163\fBt\fR or \fB1\fR, meaning \fItrue\fR, and \fBno\fR,
164\fBfalse\fR, \fBnil\fR, \fB0\fR meaning \fIfalse\fR.
165.TP
166.I unquoted string
167An unquoted string may contain letters, digits, and any of the
168following characters: \fB_\fR, \fB\-\fR, \fB.\fR, \fB/\fR,
169\fB@\fR, \fB*\fR, \fB:\fR.
170.TP
171.I quoted string
172A quoted string is any sequence of characters enclosed in
173double-quotes (\fB\(dq\fR). A backslash appearing within a quoted
174string introduces an \fIescape sequence\fR, which is replaced
175with a single character according to the following rules:
176.nf
177.ul
178 Sequence Replaced with
179 \\a Audible bell character (ASCII 7)
180 \\b Backspace character (ASCII 8)
181 \\f Form-feed character (ASCII 12)
182 \\n Newline character (ASCII 10)
183 \\r Carriage return character (ASCII 13)
184 \\t Horizontal tabulation character (ASCII 9)
185 \\v Vertical tabulation character (ASCII 11)
186 \\\\ A single backslash
187 \\\(dq A double-quote.
188.fi
189In addition, the sequence \fB\\\fInewline\fR is removed from
190the string. This allows to split long strings over several
191physical lines, e.g.:
192.sp
193.nf
194 "a long string may be\\
195 split over several lines"
196.fi
197.sp
198If the character following a backslash is not one of those specified
199above, the backslash is ignored and a warning is issued.
200
201Two or more adjacent quoted strings are concatenated, which gives
202another way to split long strings over several lines to improve
203readability. The following fragment produces the same result as the
204example above:
205.sp
206.nf
207 "a long string may be"
208 " split over several lines"
209.fi
210.TP
211.I Here-document
212A \fIhere-document\fR is a special construct that allows to introduce
213strings of text containing embedded newlines.
214
215The
216.BI "<<" "word"
217construct instructs the parser to read all the following lines up to
218the line containing only \fIword\fR, with possible trailing blanks.
219Any lines thus read are concatenated together into a single string.
220For example:
221.sp
222.nf
223 <<EOT
224 A multiline
225 string
226 EOT
227.fi
228.sp
229The body of a here-document is interpreted the same way as a
230double-quoted string, unless \fIword\fR is preceded by a backslash
231(e.g. \fB<<\\EOT\fR) or enclosed in double-quotes, in which case
232the text is read as is, without interpretation of escape sequences.
233
234If \fIword\fR is prefixed with \fB\-\fR (a dash), then all leading
235tab characters are stripped from input lines and the line containing
236\fIword\fR. Furthermore, \fB\-\fR is followed by a single space,
237all leading whitespace is stripped from them. This allows to indent
238here-documents in a natural fashion. For example:
239.sp
240.nf
241 <<- TEXT
242 Th