ucw/doc/config.txt

   1 Configuration files
   2 ===================
   3
   4 This document describes run-time configuration of libucw-based
   5 programs using config files. For compile-time configuration,
   6 see <<configure:>>.
   7
   8 [[terminology]]
   9 Terminology
  10 -----------
  11
  12 Configuration items of all modules are organized into sections.
  13 The sections form a tree structure with top-level sections corresponding
  14 to program modules.
  15
  16 Each configuration item belongs to one of the following classes:
  17
  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)
  25
  26 Both fixed- and variable-length arrays consist of items of the same
  27 type.  The basic types supported by the configuration mechanism are:
  28
  29   1. 32-bit integer
  30   2. 64-bit integer
  31   3. floating point number
  32   4. IP address
  33   5. string
  34   6. choice (one of a fixed list of strings)
  35
  36 Program modules can define their own special types (such as network
  37 masks or attribute names) and decide how are they parsed.
  38
  39 [[format]]
  40 Format of configuration files
  41 -----------------------------
  42
  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
  46 assignment command is
  47
  48   name value1 value2 ... valueN
  49
  50 or
  51
  52   name=value1 value2 ... valueN
  53
  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
  62 assignment commands:
  63
  64   Database "main db\x2b"; Directory='index/'; Weights 100 20 30 \
  65     40 50 80                            # a comment that is ignored
  66
  67 Numerical values can be succeeded by a unit.  The following units are
  68 supported:
  69
  70 [[units]]
  71
  72         d=86400         k=1000          K=1024
  73         h=3600          m=1000000       M=1048576
  74         %=0.01          g=1000000000    G=1073741824
  75
  76 Attributes of a section or a list node can be set in two ways.  First,
  77 you can write the name of the section or list, open a bracket, and then
  78 set the attributes inside the section.  For example,
  79
  80   Section1 {
  81     Attr1       value1
  82     Attr2       value2
  83     ListNode {          #creates a list and adds its first node
  84       Attr3     value3
  85       Attr4     value4
  86     }
  87     ListNode { Attr3=value5; Attr4=value6 }
  88                         #appends a new node; this is still the same syntax
  89   }
  90
  91 The second possibility is using a shorter syntax when all attributes of a
  92 section are set on one line in a fixed order.  The above example could
  93 be as well written as
  94
  95   Section1 {
  96     Attr1       value1
  97     Attr2       value2
  98     ListNode    value3 value4
  99     ListNode    value5 value6
 100   }
 101
 102 Of course, you cannot use the latter syntax when the attributes allow
 103 variable numbers of parameters.  The parser of the configuration files
 104 checks this possibility.
 105
 106 If you want to set a single attribute in some section, you can also
 107 refer to the attribute as Section.Attribute.
 108
 109 Lists support several operations besides adding a new node.  You just
 110 have to write a colon immediately after the attribute name, followed by
 111 the name of the operation.  The following operations are supported:
 112
 113 [[operations]]
 114
 115   List:clear                            # removes all nodes
 116   List:append { attr1=value1; ... }     # adds a new node at the end
 117   List:prepend { attr1=value1; ... }    # adds a new node at the beginning
 118   List:remove { attr1=search1 }         # find a node and delete it
 119   List:edit { attr1=search1 } { attr1=value1; ... }
 120                                         # find a node and edit it
 121   List:after { attr1=search1 } { ... }  # insert a node after a found node
 122   List:before { attr1=search1 } { ... } # insert a node before a found node
 123   List:copy { attr1=search1 } { ... }   # duplicate a node and edit the copy
 124   List:reset { attr=value1; ... }       # equivalent to :clear and :append
 125
 126 You can specify several attributes in the search condition and the nodes
 127 are tested for equality in all these attributes.  In the editing
 128 commands, you can either open a second block with overridden attributes,
 129 or specify the new values using the shorter one-line syntax.
 130
 131 The commands :clear, :append, and :prepend are also supported by var-length
 132 arrays.  The command :clear can also be used on string values.  The following
 133 operations can be used on bitmaps: :set (which is equal to :append and :prepend),
 134 :remove, :clear, and :all (set all bits).
 135
 136 [[include]]
 137 Including other files
 138 ---------------------
 139
 140 To include another file, use the command
 141
 142   Include another/file
 143
 144 or if the file needs not to exist
 145
 146   OptionalInclude another/file
 147
 148 (Beware that this command has to be the last one on the line.)
 149
 150 [[command_line]]
 151 Command-line parameters
 152 -----------------------
 153
 154 The default configuration file (cf_def_file possibly overriden
 155 by environment variable cf_env_file) is read before the program is started.
 156 You can use a -C option to override the name of the configuration file.
 157 If you use this parameter several times, then all those files are loaded
 158 consecutively. A parameter -S can be used to execute a configuration
 159 command directly (after loading the default or specified configuration
 160 file).  Example:
 161
 162   bin/program -Ccf/my-config -S'module.trace=2;module.logfile:clear' ...
 163
 164 If the program is compiled with debugging information, then one more
 165 parameter `--dumpconfig` is supported.  It prints all parsed configuration
 166 items and exits.
 167
 168 All these switches must be used before any other parameters of the
 169 program.
 170
 171 [[preprocess]]
 172 Preprocessing
 173 -------------
 174
 175 During compilation, all configuration files are pre-processed by a simple
 176 C-like preprocessor, which supports `#ifdef`, `#ifndef`, `#if`,
 177 `#elsif`, `#else` and `#endif` directives referring to compile-time
 178 configuration variables (the ones detected by `configure` script, you
 179 can see list of them in `obj/autoconf.h`). `#if` and `#elsif` can contain
 180 any Perl expression where each `CONFIG_xyz` configuration variable is
 181 substituted to 0 or 1 depending on its value.
 182
 183 The preprocessor also substitutes `@VARIABLE@` by the value of the variable,
 184 which must be defined.
 185
 186 [[caveats]]
 187 Caveats
 188 -------
 189
 190 Trying to access an unknown attribute causes an error, but unrecognized
 191 top-level sections are ignored.  The reason is that a common config file
 192 is used for a lot of programs which recognize only their own sections.
 193
 194 Names of sections, attributes and choices are case-insensitive. Units are
 195 case-sensitive.