| 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 -------------------------------------------------- |