7.11 Configuration File Format

The configuration file is designed to associate names and values, much like an AutoGen Definition File (see section Definitions File). Unfortunately, the file formats are different. Specifically, AutoGen Definitions provide for simpler methods for the precise control of a value string and provides for dynamically computed content. Configuration files have some established traditions in their layout. So, they are different, even though they do both allow for a single name to be associated with multiple values and they both allow for hierarchical values.

7.11.1 assigning a string value to a configurable

The basic syntax is a name followed by a value on a single line. They are separated from each other by either white space, a colon (:) or an equal sign (=). The colon or equal sign may optionally be surrounded by additional white space. If more than one value line is needed, a backslash (\) may be used to continue the value. The backslash (but not the newline) will be erased. Leading and trailing white space is always stripped from the value.

Fundamentally, it looks like this:

name  value for that name
name = another \
     multi-line value \
     for that name.
name: a *third* value for name

If you need more control over the content of the value, you may enclose the value in XML style brackets:

<name>value </name>

Within these brackets you need not (must not) continue the value data with backslashes. You may also select the string formation rules to use, just add the attribute after the name, thus: <name keep>.

‘keep’

This mode will keep all text between the brackets and not strip any white space.

‘uncooked’

This mode strips leading and trailing white space, but not do any quote processing. This is the default and need not be specified.

‘cooked’

The text is trimmed of leading and trailing white space and XML encodings are processed. These encodings are slightly expanded over the XML specification. They are specified with an ampersand followed by a value name or numeric value and then a semicolon:

‘amp’

‘lt’

‘gt’

‘quot’

‘apos’

‘#dd’

‘#xHH’

These are all per fairly standad HTML and/or XML encodings. Additionally:

‘bs’

The ASCII back space character.

‘ff’

The ASCII form feed character.

‘ht’

The ASCII horizontal (normal) tab character.

‘cr’

The ASCII carriage return character.

‘vt’

The ASCII vertical tab character.

‘bel’

The ASCII alarm bell character.

‘nl’

The ASCII new line character.

‘space’

The ASCII space character. Normally not necessary, but if you want to preserve leading or trailing space characters, then use this.

And here is an example of an XML-styled value:

<name cooked>
    This is&nl;&ht;another multi-line
&ht;string example.
</name>

The string value associated with name will be exactly the text enclosed in quotes with the encoded characters cooked as you would expect (three text lines with the last line not ending with a newline, but ending with a period).

7.11.2 integer values

A name can be specified as having an integer value. To do this, you must use the XML-ish format and specify a type attribute for the name:

<name type=integer> 1234 </name>

Boolean, enumeration and set membership types will be added as time allows. type=string is also supported, but also is the default.

7.11.3 hierarchical values

In order to specify a hierarchical value, you *must* use XML-styled formatting, specifying a type that is shorter and easier to spell:

<structured-name type=nested>
    [[....]]
</structured-name>

The ellipsis may be filled with any legal configuration file name/value assignments.

7.11.4 configuration file directives

The <? marker indicates an XML directive. There is only one directive supported: program sectioning, though two syntaxes are supported.

If, for example, you have a collection of programs that work closely together and, likely, have a common set of options, these programs may use a single, sectioned, configuration file. The file may be sectioned in either of two ways. The two ways may not be intermixed in a single configuration file. All text before the first segmentation line is processed, then only the segment that applies:

‘<?auto-options ...>’

The ... ellipsis may contain AutoOpts option processing options. Currently, that consists of one or both of:

gnu

autoopts

to indicate GNU-standard or AutoOpts-standard layout of usage and version information, and/or

misuse-usage

no-misuse-usage

to indicate whether the available options should be listed when an invalid option appears on the command line.

Anything else will be silently ignored.

‘<?program prog-name>’

The <? marker indicates an XML directive. The file is partitioned by these lines and the options are processed for the prog-name program only before the first <?program directive and the program section with a matching program name.

‘[PROG_NAME]’

This is basically an alias for <?program prog-name>, except that the program name must be upper cased and segmented only with underscores.

Segmentation does not apply if the config file is being parsed with the configFileLoad(3AutoOpts) function.

7.11.5 comments in the configuration file

Comments are lines beginning with a hash mark (#), XML-style comments (<!-- arbitrary text -->), and unrecognized XML directives.

# this is a comment
<!-- this is also
     a comment -->
<?this is
  a bad comment ;->

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.