4 This document describes run-time configuration of libucw-based
5 programs using config files. For compile-time configuration,
12 Configuration items of all modules are organized into sections.
13 The sections form a tree structure with top-level sections corresponding
16 Each configuration item belongs to one of the following classes:
18 1. single value or a fixed-length array of values
19 2. variable-length array of values
20 3. subsection with several nested attributes
21 4. list of nodes, each being an instance of a subsection
22 5. bitmap of small integers (0..31) or fixed list of strings
23 6. exceptions (items with irregular syntax; however, they always
24 appear as a sequence of strings, only the semantics differ)
26 Both fixed- and variable-length arrays consist of items of the same
27 type. The basic types supported by the configuration mechanism are:
31 3. floating point number
34 6. choice (one of a fixed list of strings)
36 Program modules can define their own special types (such as network
37 masks or attribute names) and decide how are they parsed.
40 Format of configuration files
41 -----------------------------
43 Configuration files are text files that usually set one attribute per
44 line, though it is possible to split one assignment into multiple lines
45 and/or assign several attributes in one line. The basic format of an
48 name value1 value2 ... valueN
52 name=value1 value2 ... valueN
54 The end of line means also end of a command unless it is preceded by a
55 backslash. On the other hand, a semicolon terminates the command and
56 another command can start after the semicolon. A hash starts a comment
57 that lasts until the end of the line. A value can be enclosed in
58 apostrophes or quotation marks and then it can contain spaces and/or
59 control characters, otherwise the first space or control character
60 denotes the end of the value. Values enclosed in quotation marks are
61 interpreted as C-strings. For example, the following are valid
64 Database "main db\x2b"; Directory='index/'; Weights 100 20 30 \
65 40 50 80 # a comment that is ignored
67 Numerical values can be succeeded by a unit. The following units are
73 h=3600 m=1000000 M=1048576
74 %=0.01 g=1000000000 G=1073741824
75 t=1000000000000 T=1099511627776
77 Attributes of a section or a list node can be set in two ways. First,
78 you can write the name of the section or list, open a bracket, and then
79 set the attributes inside the section. For example,
84 ListNode { #creates a list and adds its first node
88 ListNode { Attr3=value5; Attr4=value6 }
89 #appends a new node; this is still the same syntax
92 The second possibility is using a shorter syntax when all attributes of a
93 section are set on one line in a fixed order. The above example could
99 ListNode value3 value4
100 ListNode value5 value6
103 Of course, you cannot use the latter syntax when the attributes allow
104 variable numbers of parameters. The parser of the configuration files
105 checks this possibility.
107 If you want to set a single attribute in some section, you can also
108 refer to the attribute as Section.Attribute.
110 Lists support several operations besides adding a new node. You just
111 have to write a colon immediately after the attribute name, followed by
112 the name of the operation. The following operations are supported:
116 List:clear # removes all nodes
117 List:append { attr1=value1; ... } # adds a new node at the end
118 List:prepend { attr1=value1; ... } # adds a new node at the beginning
119 List:remove { attr1=search1 } # find a node and delete it
120 List:edit { attr1=search1 } { attr1=value1; ... }
121 # find a node and edit it
122 List:after { attr1=search1 } { ... } # insert a node after a found node
123 List:before { attr1=search1 } { ... } # insert a node before a found node
124 List:copy { attr1=search1 } { ... } # duplicate a node and edit the copy
125 List:reset { attr=value1; ... } # equivalent to :clear and :append
127 You can specify several attributes in the search condition and the nodes
128 are tested for equality in all these attributes. In the editing
129 commands, you can either open a second block with overridden attributes,
130 or specify the new values using the shorter one-line syntax.
132 The commands :clear, :append, and :prepend are also supported by var-length
133 arrays. The command :clear can also be used on string values. The following
134 operations can be used on bitmaps: :set (which is equal to :append and :prepend),
135 :remove, :clear, and :all (set all bits).
138 Including other files
139 ---------------------
141 To include another file, use the command
145 or if the file needs not to exist
147 OptionalInclude another/file
149 (Beware that this command has to be the last one on the line.)
152 Command-line parameters
153 -----------------------
155 The default configuration file (cf_def_file possibly overriden
156 by environment variable cf_env_file) is read before the program is started.
157 You can use a -C option to override the name of the configuration file.
158 If you use this parameter several times, then all those files are loaded
159 consecutively. A parameter -S can be used to execute a configuration
160 command directly (after loading the default or specified configuration
163 bin/program -Ccf/my-config -S'module.trace=2;module.logfile:clear' ...
165 If the program is compiled with debugging information, then one more
166 parameter `--dumpconfig` is supported. It prints all parsed configuration
169 All these switches must be used before any other parameters of the
176 During compilation, all configuration files are pre-processed by a simple
177 C-like preprocessor, which supports `#ifdef`, `#ifndef`, `#if`,
178 `#elsif`, `#else` and `#endif` directives referring to compile-time
179 configuration variables (the ones detected by `configure` script, you
180 can see list of them in `obj/autoconf.h`). `#if` and `#elsif` can contain
181 any Perl expression where each `CONFIG_xyz` configuration variable is
182 substituted to 0 or 1 depending on its value.
184 The preprocessor also substitutes `@VARIABLE@` by the value of the variable,
185 which must be defined.
191 Trying to access an unknown attribute causes an error, but unrecognized
192 top-level sections are ignored. The reason is that a common config file
193 is used for a lot of programs which recognize only their own sections.
195 Names of sections, attributes and choices are case-insensitive. Units are