mdw@git.distorted.org.uk Git - runlisp/blob - runlisp.conf.5

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