Go to the first, previous, next, last section, table of contents.

Configuration Files

Configuration files consist of one or more blocks, called stanza (i believe this comes from AIX), in which values are assigned to variables.

Lines In The Configuration File

At the moment lines may be up to 1024 characters long. Long lines may be splitted, but the 1024 character limit stays (splitted lines count as one line).

To mark a line as splitted escape the last character with a backslash (\). 

# This is a  \
  comment line 
var=a long \
value

is equal to: 

# This is a     comment line
var=a long value

Whitespace is preserved except at the begin and the and of the line after glueing together the splittet lines. The backslash and the lineend simply vanish.

Stanzas in configuration files

Each stanza consist of a label line and zero to many variable assignments (this basically means: a stanza may be totally empty).

The label line ends with a colon and has no equals sign (=) in it. Before the colon are one or more words (separated with white space). Each one is a name for this stanza. Alternatively you may include the label in brackets ([ and ]), but then you must use only one stanza name on that line (this is not a serious problem).

Names may be found in different label lines (i.e. in different stanzas). Each stanza with this name will be read if the stanza is read, making it possible to share assignments between many stanzas (but there are better ways, see section Including Stanzas And Files).

A stanza ends with the next stanza, or the end of the file.

An example: 

stanza1:
    variable1="hallo"
[stanza2]
    variable2="hallo Du"
stanza1 stanza3:
    variable3="Hallo Du da"

If the stanza stanza1 is read then variable1 and variable3 are set to the new values. If stanza3 is read then only variable3 it set.

It is possible to read all stanzas matching a certain wildcard. To do this one gives a wildcard pattern instead of a stanza name to cl_getstanza. This is called a wildcard read. For more details see section Reading and writing.

In the following example all stanzas will be read if *ab* is used as a pattern: 

aber:
ab:
hinab:

Comments in Configuration Files

Two kinds of comments are recognized. This first is a one-line-comment, on a line beginning with a # (whitespace before this will be ignored). A comment line is ignored. The following are legal comments: 

# comment
#        comment
        #comment

but the following are not recognized as comments: 

var=value # assign a new value
label: # a new stanza begins

The second line is completely ignored, the first one assigns value # assign a new value to var.

The second kind of comments are block comments. They begin with a line beginning with ## (again, whitespace before this will be ignored), and end with the next such line. Example 

# the next line begins a block comment
## block comment starts here
....
## block comments end here

The following is no good style, but possible: 

label1:
    var1=value
# label2 is not needed anymore \
label2:
    var2=value

Variables in Configuration Files

Variables get there values through assignment in the configuration files. An assignment looks like this: 

variable_name=value

Whitespace bevor the equals sign are ignored, whitespace after is is ignored. Whitespace at the end of the line is ignored.

Variable names are caseinsensitive. No difference between minus sign and underscore is made, they are treated as equal.

There are many different variable types:

boolean
Boolean variables get a true value assigned if the string begins with one of tTyYjJwW] and a false value if the string starts with one of fFnN. If none of these character matches the string is treated as number, and true is assigned if the number is not zero. The following assignment are true: and these are false:
short
a short number. The typical values range from -32768 to 32767.
number
a long number. The typical value range is {+|-}2^32.
string
a string.
string array
a array of strings. Each assignment to the variable fills another element in the string array. The maximal number of strings in one array is limited, see section Limitations.
enumerations
characters
directory names

Including Stanzas And Files

Command: includestanza stanzaname
Includes the stanza stanzaname as part of the stanza read at the time the includestanza statement is found.

Command: include filename [stanzaname]
Includes the stanza stanzaname from the configuration files filename. If stanzaname is left out the whole configuration file is read (you can achieve the same with writing include filename *.

Special constructs in the configuration file

var ~= value
forces interpretation of value. This is controlled by an array of tip_t either attached to the configuration file handle or statically compiled into the library. The one included in the library contains: 
static tip_t cl_tiptab[]={
    { '\0', "${literal",   0, tip_literal },
    { '\\', NULL,        0, tip_backslash },
    { '~',  NULL,        0, tip_tilde },
    { '\0', "$[",        0, tip_conditional },
    { '\0', "${strip",   0, tip_strip },
    { '\0', "${force",   0, tip_force },
    { '\0', "${macro",   0, tip_macro },
    { '\0', "${defmacro",   0, tip_defmacro },
    { '\0', "${undefmacro",   0, tip_undefmacro },
    { '$',  NULL,        0, tip_dollar },
    { '\0', NULL,        0, NULL }
};
a tip_t table attache
append var = value
appends value to the actual value of the var. This is only recognized for CL_STRING (where both strings are concatenated with a space sign in between) and CL_DIRNAME (where old and new value are simply glued together) and ignored otherwise.
override var = value
resets the var before parsing value, and is only recognized for CL_LIST and CL_BITFIELD. Example: 
bitfield=bit0
bitfield=bit2
and 
bitfield=bit0|bit2
lead to equal results. The same is true for 
bitfield=bit0
override bitfield=bit2
and 
bitfield=bit2

Go to the first, previous, next, last section, table of contents.