diff options
Diffstat (limited to 'doc/argot_config.5')
-rw-r--r-- | doc/argot_config.5 | 352 |
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 | ||
22 | A configuration file consists of statements and comments. | ||
23 | .PP | ||
24 | There are three classes of lexical tokens: keywords, values, and | ||
25 | separators. Blanks, tabs, newlines and comments, collectively called | ||
26 | \fIwhite space\fR are ignored except as they serve to separate | ||
27 | tokens. Some white space is required to separate otherwise adjacent | ||
28 | keywords and values. | ||
29 | .SH COMMENTS | ||
30 | Comments may appear anywhere where white space may appear in the | ||
31 | configuration file. There are two kinds of comments: | ||
32 | single-line and multi-line comments. Single-line comments start | ||
33 | with | ||
34 | .B # | ||
35 | or | ||
36 | .B // | ||
37 | and 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 | ||
47 | characters | ||
48 | .B /* | ||
49 | (slash, star) and continue until the first occurrence of | ||
50 | .B */ | ||
51 | (star, slash). | ||
52 | .PP | ||
53 | Multi-line comments cannot be nested. However, single-line comments | ||
54 | may well appear within multi-line ones. | ||
55 | .SS "Pragmatic Comments" | ||
56 | Pragmatic comments are similar to usual single-line comments, | ||
57 | except that they cause some changes in the way the configuration is | ||
58 | parsed. Pragmatic comments begin with a | ||
59 | .B # | ||
60 | sign 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 | ||
67 | Include the contents of the file \fIfile\fR. There are three possible | ||
68 | use cases. | ||
69 | |||
70 | If \fIfile\fR is an absolute file name, the named file is included. | ||
71 | An error message will be issued if it does not exist. | ||
72 | |||
73 | If \fIfile\fR contains wildcard characters (\fB*\fR, \fB[\fR, | ||
74 | \fB]\fR or \fB?\fR), it is interpreted as shell globbing pattern and | ||
75 | all files matching that pattern are included, in lexicographical | ||
76 | order. If no files match the pattern, the statement is silently | ||
77 | ignored. | ||
78 | |||
79 | Otherwise, the form with angle brackets searches for file in the | ||
80 | \fIinclude search path\fR, while the second one looks for it in the | ||
81 | current working directory first, and, if not found there, in the | ||
82 | include search path. If the file is not found, an error message will | ||
83 | be issued. | ||
84 | .sp | ||
85 | The 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 | ||
91 | where \fIprefix\fR stands for the installation prefix (normally | ||
92 | \fB/usr\fR or \fB/usr/local\fR), \fIPROGNAME\fR stands for the name of | ||
93 | the program which uses the configuration file, and \fIVERSION\fR for | ||
94 | its version number. | ||
95 | .sp | ||
96 | The include search path can be modified using the | ||
97 | .BI argot_include_path_setup () | ||
98 | and | ||
99 | .BI argot_include_path_setup_v () | ||
100 | functions. Refer to | ||
101 | .BR argot_include_path_setup (3), | ||
102 | for a detailed discussion. | ||
103 | .TP | ||
104 | .BR "#include_once <" "file" > | ||
105 | .PD 0 | ||
106 | .TP | ||
107 | .BR "#include_once " "file" | ||
108 | .PD | ||
109 | Same as \fB#include\fR, except that, if the \fIfile\fR has already | ||
110 | been 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 | ||
117 | This line causes the parser to believe, for purposes of error | ||
118 | diagnostics, that the line number of the next source line | ||
119 | is given by \fInum\fR and the current input file is named by | ||
120 | \fIfile\fR. If the latter is absent, the remembered file name | ||
121 | does not change. | ||
122 | .TP | ||
123 | .BR "# " "num" " \(dq" "file" "\(dq" | ||
124 | This is a special form of the \fB#line\fR statement, understood for | ||
125 | compatibility with the C preprocessor. | ||
126 | .PP | ||
127 | These statements provide a rudimentary preprocessing | ||
128 | features. For more sophisticated ways to modify configuration before | ||
129 | parsing, see \fBPREPROCESSOR\fR. | ||
130 | .SH STATEMENTS | ||
131 | .SS "Simple statement" | ||
132 | A \fIsimple statement\fR consists of a keyword and value | ||
133 | separated by any amount of whitespace. Simple statement is terminated | ||
134 | with a semicolon (\fB;\fR). | ||
135 | .PP | ||
136 | The following is a simple statement: | ||
137 | .sp | ||
138 | .RS 4 | ||
139 | .nf | ||
140 | standalone yes; | ||
141 | pidfile /var/run/slb.pid; | ||
142 | .RE | ||
143 | .fi | ||
144 | .PP | ||
145 | A \fIkeyword\fR begins with a letter and may contain letters, | ||
146 | decimal digits, underscores (\fB_\fR) and dashes (\fB-\fR). | ||
147 | Examples of keywords are: | ||
148 | .sp | ||
149 | .RS 4 | ||
150 | .nf | ||
151 | expression | ||
152 | output-file | ||
153 | .RE | ||
154 | .fi | ||
155 | .PP | ||
156 | A \fIvalue\fR can be one of the following: | ||
157 | .TP | ||
158 | .I number | ||
159 | A number is a sequence of decimal digits. | ||
160 | .TP | ||
161 | .I boolean | ||
162 | A 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 | ||
167 | An unquoted string may contain letters, digits, and any of the | ||
168 | following characters: \fB_\fR, \fB\-\fR, \fB.\fR, \fB/\fR, | ||
169 | \fB@\fR, \fB*\fR, \fB:\fR. | ||
170 | .TP | ||
171 | .I quoted string | ||
172 | A quoted string is any sequence of characters enclosed in | ||
173 | double-quotes (\fB\(dq\fR). A backslash appearing within a quoted | ||
174 | string introduces an \fIescape sequence\fR, which is replaced | ||
175 | with 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 | ||
189 | In addition, the sequence \fB\\\fInewline\fR is removed from | ||
190 | the string. This allows to split long strings over several | ||
191 | physical lines, e.g.: | ||
192 | .sp | ||
193 | .nf | ||
194 | "a long string may be\\ | ||
195 | split over several lines" | ||
196 | .fi | ||
197 | .sp | ||
198 | If the character following a backslash is not one of those specified | ||
199 | above, the backslash is ignored and a warning is issued. | ||
200 | |||
201 | Two or more adjacent quoted strings are concatenated, which gives | ||
202 | another way to split long strings over several lines to improve | ||
203 | readability. The following fragment produces the same result as the | ||
204 | example above: | ||
205 | .sp | ||
206 | .nf | ||
207 | "a long string may be" | ||
208 | " split over several lines" | ||
209 | .fi | ||
210 | .TP | ||
211 | .I Here-document | ||
212 | A \fIhere-document\fR is a special construct that allows to introduce | ||
213 | strings of text containing embedded newlines. | ||
214 | |||
215 | The | ||
216 | .BI "<<" "word" | ||
217 | construct instructs the parser to read all the following lines up to | ||
218 | the line containing only \fIword\fR, with possible trailing blanks. | ||
219 | Any lines thus read are concatenated together into a single string. | ||
220 | For example: | ||
221 | .sp | ||
222 | .nf | ||
223 | <<EOT | ||
224 | A multiline | ||
225 | string | ||
226 | EOT | ||
227 | .fi | ||
228 | .sp | ||
229 | The body of a here-document is interpreted the same way as a | ||
230 | double-quoted string, unless \fIword\fR is preceded by a backslash | ||
231 | (e.g. \fB<<\\EOT\fR) or enclosed in double-quotes, in which case | ||
232 | the text is read as is, without interpretation of escape sequences. | ||
233 | |||
234 | If \fIword\fR is prefixed with \fB\-\fR (a dash), then all leading | ||
235 | tab characters are stripped from input lines and the line containing | ||
236 | \fIword\fR. Furthermore, \fB\-\fR is followed by a single space, | ||
237 | all leading whitespace is stripped from them. This allows to indent | ||
238 | here-documents in a natural fashion. For example: | ||
239 | .sp | ||
240 | .nf | ||
241 | <<- TEXT | ||
242 | Th |