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