Commit | Line | Data |
---|---|---|
8996f767 MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" Manual for `runlisp' configuration files | |
4 | .\" | |
5 | .\" (c) 2020 Mark Wooding | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
10 | .\" This file is part of Runlisp, a tool for invoking Common Lisp scripts. | |
11 | .\" | |
12 | .\" Runlisp is free software: you can redistribute it and/or modify it | |
13 | .\" under the terms of the GNU General Public License as published by the | |
14 | .\" Free Software Foundation; either version 3 of the License, or (at your | |
15 | .\" option) any later version. | |
16 | .\" | |
17 | .\" Runlisp is distributed in the hope that it will be useful, but WITHOUT | |
18 | .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or | |
19 | .\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License | |
20 | .\" for more details. | |
21 | .\" | |
22 | .\" You should have received a copy of the GNU General Public License | |
23 | .\" along with Runlisp. If not, see <https://www.gnu.org/licenses/>. | |
24 | . | |
25 | .ie t \{\ | |
26 | . ds o \(bu | |
27 | . if \n(.g \{\ | |
28 | . fam P | |
29 | . ev an-1 | |
30 | . fam P | |
31 | . ev | |
32 | . \} | |
33 | .\} | |
34 | .el \{\ | |
35 | . ds o o | |
36 | .\} | |
37 | . | |
38 | .de hP | |
39 | .IP | |
40 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
41 | .. | |
42 | .ds , \h'.16667m' | |
43 | . | |
44 | .\"-------------------------------------------------------------------------- | |
45 | .TH runlisp.conf 5 "27 August 2020" "Mark Wooding" | |
46 | .SH NAME | |
47 | runlisp.conf \- configuration files for runlisp | |
48 | . | |
49 | .\"-------------------------------------------------------------------------- | |
50 | .SH DESCRIPTION | |
51 | . | |
52 | .SS "General syntax" | |
53 | In summary, | |
54 | a configuration file is structured as a collection of assignments | |
55 | .I variable | |
56 | .B = | |
57 | .IR value , | |
58 | gathered into named sections by header lines | |
59 | .BI [ section ]\fR. | |
60 | .PP | |
61 | Comments are indicated by a semicolon | |
62 | .RB ` ; ' | |
63 | in the leftmost column, | |
64 | and extend to the end of the line; | |
65 | comments and lines consisting only of whiteapace are ignored | |
66 | and have no effect whatever. | |
67 | Semicolons not in the first column do | |
68 | .I not | |
69 | introduce comments, | |
70 | and have no special meaning. | |
71 | .PP | |
72 | A | |
73 | .I name | |
74 | is a non-empty sequence of ASCII alphanumeric characters, | |
75 | or the special constituent characters | |
76 | .RB ` \- ', | |
77 | .RB ` _ ', | |
78 | .RB ` . ', | |
79 | .RB ` / ', | |
80 | .RB ` * ', | |
81 | .RB ` + ', | |
82 | .RB ` *% ', | |
83 | or | |
84 | .RB ` @ '. | |
85 | For example, | |
86 | .RB ` foo ', | |
87 | .RB ` 12345 ', | |
88 | .RB ` \-2.718 ', | |
89 | .RB ` 113/355 ', | |
90 | .RB ` image-dir ', | |
91 | .RB ` @%IMAGEDIR ', | |
92 | and | |
93 | .RB ` *organa-solo* ' | |
94 | are all names, but | |
95 | .RB ` foo:bar ' | |
96 | .RB ` happy? ' | |
97 | and | |
98 | .RB ` $3.95 ' | |
99 | are not. | |
100 | Names beginning with | |
101 | .RB ` @ ' | |
102 | are reserved for use by the | |
103 | .B runlisp | |
104 | programs; | |
105 | names beginning with | |
106 | .RB ` % ' | |
107 | or | |
108 | .RB ` @% ' | |
109 | are by convention private. | |
110 | .PP | |
111 | A | |
112 | .I section header | |
113 | is a line of the form | |
114 | .IP | |
115 | .BI [ section ] | |
116 | .PP | |
117 | where | |
118 | .I section | |
119 | is a name, as defined above. | |
120 | There may be whitespace before and after the | |
121 | .I name | |
122 | or after the | |
123 | .RB ` ] '. | |
124 | Section headers need not have distinct names. | |
125 | Subsequent assignments are applied to the section called | |
126 | .IR name , | |
127 | up until the next section header, or the end of the file. | |
128 | Assignments prior to the first section header in a file | |
129 | are applied to the | |
130 | .B @CONFIG | |
131 | section. | |
132 | .PP | |
133 | An | |
134 | .I assignment | |
135 | begins with a line of the form | |
136 | .IP | |
137 | .I variable | |
138 | .B = | |
139 | .I rest | |
140 | .PP | |
141 | where | |
142 | .I variable | |
143 | is a name, as defined above, | |
144 | and it includes all subsequent | |
145 | (non-empty, non-comment) | |
146 | lines up to, but not including, | |
147 | the next line which does | |
148 | .I not | |
149 | begin with whitespace or a semicolon, | |
150 | or the end of the input file. | |
151 | There may be space before or after the | |
152 | .RB ` = '. | |
153 | The | |
154 | .I value | |
155 | assigned consists of the text of the initial line following the | |
156 | .RB ` = ' | |
157 | character | |
158 | (shown as | |
159 | .I rest | |
160 | above), | |
161 | together with the contents of the subsequent lines; | |
162 | initial and trailing whitespace is removed from each piece, | |
163 | and the (nonempty) pieces are joined, | |
164 | separated by single spaces. | |
165 | We say that a assignment | |
166 | assigns a value to the variable | |
167 | in some section \(en | |
168 | namely, the section in which the assignment is applied. | |
169 | .PP | |
170 | For example, | |
171 | consider the following file. | |
172 | .IP | |
173 | .ft B | |
174 | .nf | |
175 | long = | |
176 | one | |
177 | ||
178 | two | |
179 | ; this line is a comment | |
180 | ; not a comment | |
181 | three | |
182 | ||
183 | short = just a quick note | |
184 | .fi | |
185 | .ft P | |
186 | .PP | |
187 | Then | |
188 | .B long | |
189 | is assigned the value | |
190 | .RB ` "one two ; not a comment three" ', | |
191 | and | |
192 | .B short is assigned | |
193 | .RB ` "just a quick note" '. | |
194 | .PP | |
195 | The assignments applied to a section | |
196 | need not have distinct variable names. | |
197 | Only the last assignment to a particular variable name in a section is | |
198 | .IR effective ; | |
199 | the earlier assignments are simply ignored. | |
200 | If an effective assignment assigns a value to a variable in a section, | |
201 | we say that the variable is | |
202 | .I set | |
203 | to that value in the section. | |
204 | . | |
205 | .SS "Lookup and inheritance" | |
206 | A section may have zero or more | |
207 | .I parent | |
208 | sections. | |
209 | .PP | |
210 | The | |
211 | .BR @BUILTIN , | |
212 | .BR @CONFIG , | |
213 | and | |
214 | .B @ENV | |
215 | sections have no parents. | |
216 | The | |
217 | .B @CONFIG | |
218 | section has one parent, namely | |
219 | .BR @BUILTIN . | |
220 | .PP | |
221 | If the variable | |
222 | .B @parents | |
223 | is set in a section other than one of those named above, | |
224 | then it must consist of a space- or comma-separated list | |
225 | of names, | |
226 | which name the section's parents. | |
227 | Currently, the parents need not be distinct, | |
228 | though duplicates have no effect other than slowing down lookup. | |
229 | The order in which parents are listed is not significant. | |
230 | If | |
231 | .B @parents | |
232 | is not set in a section other than one of those named above, | |
233 | then by default it has one parent, namely | |
234 | .BR @COMMON . | |
235 | .PP | |
236 | It is currently possible to build a cyclic structure of parent links. | |
237 | This is not recommended. | |
238 | If lookup (explained below) detects a cycle | |
239 | then it will report a fatal error, | |
240 | but cycles may exist without being detected. | |
241 | .PP | |
242 | A variable is | |
243 | .I "looked up" | |
244 | in a section as follows. | |
245 | .hP 1. | |
246 | If there is an effective assignment | |
247 | of a value to that variable in the section | |
248 | then lookup finds that assignment. | |
249 | .hP 2. | |
250 | If the section has no parents, | |
251 | then lookup fails. | |
252 | .hP 3. | |
253 | Otherwise, the variable is looked up in each of the section's parents. | |
254 | If none of these lookups succeeds, then the lookup fails. | |
255 | If all of the successful lookups found the | |
256 | .I "same assignment" | |
257 | (not just the same value!) | |
258 | then lookup finds that assignment. | |
259 | Otherwise, the lookup reports an error. | |
260 | . | |
261 | .SS "Expansion and word-splitting" | |
262 | A value can be | |
263 | .I expanded | |
264 | relative to some home section, | |
265 | and optionally split into words. | |
266 | .PP | |
267 | Not all values are | |
268 | .IR expandable . | |
269 | Values set by assignments in a configuration file are always expandable. | |
270 | Values set on the command line \(en in | |
271 | .B \-o | |
272 | options \(en are not expandable. | |
273 | Values in the | |
274 | .B @ENV | |
275 | section from environment variables (see below) are not expandable. | |
276 | Some values set in the | |
277 | .B @BUILTIN | |
278 | section are expandable and some are not. | |
279 | Applying expansion to a value that is not expandable | |
280 | simply results in that same value, unchanged. | |
281 | .PP | |
282 | Applying expansion to an expandable value | |
283 | produces a result string as follows. | |
284 | The value is scanned from start to end. | |
285 | .hP \*o | |
286 | A backslash | |
287 | .RB ` \e ' | |
288 | is discarded, but the immediately following character | |
289 | is copied to the output without further inspection. | |
290 | .hP \*o | |
291 | A | |
292 | .I variable substitution | |
293 | takes the form | |
294 | .BR ${ [ \c | |
295 | .IB sect : \c | |
296 | .RI ] var \c | |
297 | .RB [ | \c | |
298 | .IR filter ]... \c | |
299 | .RB [ ? \c | |
300 | .IR alt ] \c | |
301 | .BR } . | |
302 | A variable named | |
303 | .I var | |
304 | is looked up in the section named | |
305 | .IR sect , | |
306 | or, if omitted, in the home section. | |
307 | If the lookup succeeds, | |
308 | then the value is expanded, | |
309 | processed by the | |
310 | .IR filter s | |
311 | (explained below), | |
312 | and appended to the output. | |
313 | If the lookup failed, | |
314 | and | |
315 | .BI ? alt | |
316 | is present, | |
317 | then | |
318 | .I alt | |
319 | is expanded and appended to the output. | |
320 | Otherwise, | |
321 | if the lookup fails and there is no | |
322 | .I alt | |
323 | text, then an error is reported. | |
324 | .IP | |
325 | A filter | |
326 | .B u | |
327 | causes the expanded value to be converted to uppercase; | |
328 | similarly, | |
329 | .B l | |
330 | causes the expanded value to be converted to lowercase. | |
331 | A filter | |
332 | .B q | |
333 | causes a backslash to be inserted before each | |
334 | backslash or double-quote character in the expanded value, | |
335 | so that this can be used as part of a quoted Common Lisp string. | |
336 | .hP \*o | |
337 | A | |
338 | .I conditional | |
339 | takes the form | |
340 | .BR $? [ \c | |
341 | .IB sect : \c | |
342 | .RI ] var \c | |
343 | .BI { conseq \c | |
344 | .RB [ | \c | |
345 | .IR alt ] \c | |
346 | .BR } . | |
347 | A variable named | |
348 | .I var | |
349 | is looked up in the section named | |
350 | .IR sect , | |
351 | or, if omitted, in the home section. | |
352 | If the lookup succeeds, then | |
353 | .I conseq | |
354 | is expanded and appended to the output; | |
355 | otherwise, if | |
356 | .I alt | |
357 | is present, then it is expanded and appended to the output; | |
358 | otherwise, nothing happens. | |
359 | .hP \*o | |
360 | A dollar sign which doesn't introduce one of the forms above | |
361 | is invalid, and a fatal error is reported. | |
362 | .hP \*o | |
363 | Any other characters are simply appended to the output. | |
364 | .PP | |
365 | Word-splitting is similar but more complex. | |
366 | The result is not a string, but a sequence of strings. | |
367 | At any given point in this procedure, | |
368 | there may be a partially constructed word, | |
369 | or there might not. | |
370 | .hP \*o | |
371 | Outside of quotes (see below), | |
372 | whitespace serves to separate words. | |
373 | When a whitespace character is encountered, | |
374 | if there is a word under construction, | |
375 | then it is finished and added to the output list; | |
376 | otherwise it is simply ignored. | |
377 | .hP \*o | |
378 | If a backslash is encountered, | |
379 | then a word is started if there is none currently under construction, | |
380 | and the character following the backslash is added to the current word. | |
381 | .hP \*o | |
382 | If a single-quote character | |
383 | .RB ` ' ' | |
384 | is encountered, | |
385 | then a word is started if there is none currently under construction, | |
386 | and | |
387 | .I all | |
388 | characters up to the next single quote | |
389 | are added to the current word. | |
390 | This includes double quotes, dollar signs, and backslashes. | |
391 | (Neither of the two single quotes is appended to the current word.) | |
392 | .hP \*o | |
393 | If a double-quote character | |
394 | .RB ` """" ' | |
395 | is encountered, | |
396 | then a word is started if there is none currently under construction. | |
397 | Until the next double quote is encountered, | |
398 | whitespace and single quotes treated literally, | |
399 | and simply added to the current word; | |
400 | backslashes can be used to escape characters, | |
401 | such as double quotes, | |
402 | as usual. | |
403 | .hP \*o | |
404 | If a | |
405 | .BR $ -expansion | |
406 | \(en a variable substitution or conditional (as described above) \(en | |
407 | is encountered | |
408 | and there is a current word under construction, | |
409 | then the result of the | |
410 | .BR $ -expansion | |
411 | is appended to the current word. | |
412 | If there is no current word, | |
413 | then the variable value, or consequent or alternative text, | |
414 | is subjected to word splitting in addition to expansion, | |
415 | and the resulting words appended to the output sequence. | |
416 | .hP \*o | |
417 | If any other character is encountered, | |
418 | then a word is started if there is none currently under construction, | |
419 | and the character is appended to the current word. | |
420 | .PP | |
421 | One case which deserves attention: | |
422 | if a | |
423 | .BR $ -expansion | |
424 | is encountered outside of a word, | |
425 | so that the result is subject to word splitting, | |
426 | then an error is reported if a new word is started | |
427 | without there being whitespace between the closing brace of the | |
428 | .B $ -expansion | |
429 | and the character which started the new word. | |
430 | For example, | |
431 | .IP | |
432 | .B "bad = one ${x}two" | |
433 | .PP | |
434 | would be invalid in a word-splitting context. | |
435 | . | |
436 | .SS "Predefined variables in @BUILTIN" | |
437 | The | |
438 | .B @BULITIN | |
439 | Section has no parents. | |
440 | You should not override its settings in configuration files. | |
441 | it holds a number of variables set by the | |
442 | .B runlisp | |
443 | programs. | |
444 | .TP | |
445 | .B @data-dir | |
446 | The directory in which | |
447 | .BR runlisp 's | |
448 | auxiliary data files and scripts are located. | |
449 | This is determined by the | |
450 | .B RUNLISP_DATADIR | |
451 | environment variable, | |
452 | the | |
453 | .B data-dir | |
454 | variable in the | |
455 | .B @CONFIG | |
456 | section, | |
457 | or a value determined at compile time. | |
458 | .TP | |
459 | .B @ecl-opt | |
460 | The preferred option prefix for ECL, either | |
461 | .RB ` \- ' | |
462 | or | |
463 | .RB ` \-\- '. | |
464 | (For some reason, | |
465 | the ECL developers are changing | |
466 | the way ECL recognizes command-line options, | |
467 | because they think that the minor aesthetic improvement | |
468 | is worth breaking everyone's scripts.) | |
469 | This is determined by the | |
470 | .B ecl-opt | |
471 | variable in the | |
472 | .B @CONFIG | |
473 | section, | |
474 | or a value determined at compile time. | |
475 | .TP | |
476 | .B @image-dir | |
477 | The directory in which | |
478 | .B runlisp | |
479 | looks for, and | |
480 | .B dump-runlisp-image | |
481 | stores, custom Lisp images. | |
482 | This is determined by the | |
483 | .B RUNLISP_IMAGEDIR | |
484 | environment variable, | |
485 | the | |
486 | .B image-dir | |
487 | variable in the | |
488 | .B @CONFIG | |
489 | section, | |
490 | or a value determined at compile time. | |
491 | .TP | |
492 | .B @image-new | |
493 | Set by | |
494 | .BR dump-runlisp-image (1) | |
495 | to the filename that a | |
496 | .B dump-image | |
497 | command should create. | |
498 | .RB ( dump-runlisp-image | |
499 | will rename the image into place itself, | |
500 | if the command completes successfully.) | |
501 | .TP | |
502 | .B @image-out | |
503 | Set by | |
504 | .BR dump-runlisp-image (1) | |
505 | to the filename of the intended output image. | |
506 | (Don't use this in | |
507 | .B dump-image | |
508 | commands: use | |
509 | .B @image-new | |
510 | instread.) | |
511 | .TP | |
512 | .B @script | |
513 | Set by | |
514 | .BR runlisp (1) | |
515 | to the name of the script being invoked. | |
516 | .TP | |
517 | .B @tmp-dir | |
518 | Set by | |
519 | .BR dump-runlisp-image (1) | |
520 | to be the name of a directory in which a | |
521 | .B dump-image | |
522 | command can put temporary files. | |
523 | . | |
524 | .SS "Other special variables" | |
525 | In every section, the section's name | |
526 | is automatically assigned to the variable | |
527 | .BR @name . | |
528 | This variable | |
529 | .I can | |
530 | be overridden by an explicit assignment, | |
531 | but this is not recommended. | |
532 | . | |
533 | .\"-------------------------------------------------------------------------- | |
534 | . | |
535 | .SH BUGS | |
536 | .hP \*o | |
537 | . | |
538 | .SH SEE ALSO | |
539 | .BR dump-runlisp-image (1), | |
540 | .BR query-runlisp-config (1), | |
541 | .BR runlisp (1). | |
542 | . | |
543 | .SH AUTHOR | |
544 | Mark Wooding, <mdw@distorted.org.uk> | |
545 | . | |
546 | .\"----- That's all, folks -------------------------------------------------- |