1 Configuration and command line parser
2 =====================================
4 Libucw contains a parser for configuration files described in
7 The principle is you specify the structure of the configuration file,
8 the section names, variable names and types and your C variables that
9 are assigned to them. Then you run the parser and it fills your
10 variables with the values from the configuration file.
12 It is modular. It means you do not have to write all configuration at
13 the same place, you just declare the parts you need locally and do not
14 care about the other parts.
16 The command line parser has the same interface as unix getopt_long(),
17 but handles setting of configuration files and configuration values
21 * <<ex_structure,The structure>>
23 - <<deep,Getting deeper>>
24 * <<conf_multi,Arrays and lists>>
25 * <<reload,Reloading configuration>>
26 * <<custom_parser,Creating custom parsers>>
28 - <<conf_h,ucw/conf.h>>
29 * <<conf_types,Data types>>
30 * <<conf_macros,Convenience macros>>
31 * <<alloc,Memory allocation>>
32 * <<journal,Undo journal>>
33 * <<declare,Section declaration>>
34 * <<bparser,Parsers for basic types>>
35 - <<getopt_h,ucw/getopt.h>>
36 * <<conf_load,Safe configuration loading>>
37 * <<conf_direct,Direct access>>
38 * <<conf_dump,Debug dumping>>
39 * <<conf_journal,Journaling control>>
40 * <<conf_getopt,Loading by cf_getopt()>>
45 If you want to just load simple configuration, this is the part you
46 want to read. This simple example should give you the overview. Look
47 into the <<conf_macros,convenience macros>> section to see list of
48 supported data types, sections, etc.
51 Let's say you have configuration file with this content and want to
62 First, you declare the structure and let the configuration parser know
68 static char *hw_text = "Hello world";
69 static int hw_count = 1;
70 static int hw_wait_answer = 0;
72 static struct cf_section hw_config = {
74 CF_STRING("Text", &hw_text),
75 CF_INT("Count", &hw_count),
76 CF_INT("WaitAnswer", &hw_wait_answer),
81 static void CONSTRUCTOR hw_init(void) {
82 cf_declare_section("HelloWorld", &hw_config, 0);
85 The variables are used to store the loaded values. Their initial
86 values work as default, if nothing else is loaded. The hw_config()
87 structure assigns the variables to configuration names. The hw_init()
88 function (because of the `CONSTRUCTOR` macro) is run before main()
89 is called and it plugs in the whole section to the parser (alternatively,
90 you can call @cf_declare_section() at the start of your main()).
92 You can plug in as many configuration sections as you like, from
93 various places across your code.
98 Suppose you need to parse the command line arguments and load the
99 configuration. Then @cf_getopt() is there for you: it works like
100 the the traditional @getopt() from the C library, but it also handles
104 #include <ucw/conf.h>
105 #include <ucw/getopt.h>
107 static char short_opts[] = CF_SHORT_OPTS "v";
108 static struct option long_opts[] = {
110 { "verbose", 0, 0, 'v' },
116 int main(int argc, char *argv[]) {
117 cf_def_file = "default.cf";
119 while((opt = cf_getopt(argc, argv, short_opts, long_opts, NULL)) >= 0)
121 case 'v': verbose = 1; break;
122 default: fprintf("Unknown option %c\n", opt); return 1;
126 The `short_opts` and `long_opts` variables describe the command line
127 arguments. Notice the `CF_SHORT_OPTS` and `CF_LONG_OPTS` macros. They
128 add the `-S` and `-C` options for the configuration parser as described
129 in <<config:>>. These options are handled internally by @cf_getopt().
131 You can rely on the configuration files having been loaded before the
132 first of your program's options is parsed.
138 Since the configuration system is somehow complicated, this part gives
139 you a little overview of what you can find and where.
145 It is sometime needed to have multiple items of the same type. There
146 are three ways to do that:
149 An array with fixed maximum length. You provide
150 the length and already allocated array which is filled with items.
151 The configuration may contain less than the maximum length items.
153 For example, you can have an static array of five unsigned integers:
155 static uns array = { 1, 2, 3, 4, 5 };
157 static struct cf_section section = {
159 CF_UNS_ARY("array", array, 5),
165 Similar to static array, but you provide pointer
166 to pointer to the given item (eg. if you want dynamic array of
167 integers, you give `**int`). The parser allocates an array of needed
168 size. You can use the <<def_DARY_LEN,`DARY_LEN`>> macro to find out
169 the number of elements actually loaded.
171 If you want dynamic array of strings, you would use:
173 static char *array[];
175 static struct cf_section section = {
177 CF_STRING_DYN("array", &array, CF_ANY_NUM),
183 Linked lists based on <<clist:>>. You provide description
184 of single node and pointer to the
185 <<clist:struct_clist,`struct clist`>> variable. All the nodes will
186 be created dynamically and put there.
188 First element of your structure must be <<clist:type_cnode,`cnode`>>.
190 The first example is list of strings and uses <<clist:simple,simple
194 static struct cf_section section = {
196 CF_LIST("list", &list, &cf_string_list_cofnig),
201 Another example, describing how to create more complicated list node
202 than just a string can be found at the <<def_CF_TYPE,`CF_TYPE`>> macro.
205 Reloading configuration
206 ~~~~~~~~~~~~~~~~~~~~~~~
208 The configuration system allows you to reload configuration at
209 runtime. The new config changes the values against the default values.
210 It means, if the default value for variable `A` is `10`, the currently
211 loaded config sets it to `42` and the new config does not talk about
212 this variable, `A` will have a value of `10` after a successful load.
214 Furthermore, if the loading of a new configuration fails, the current
215 configuration is preserved.
217 All this is done with <<journal,config journaling>>. The load of the
218 first config creates a journal entry. If you try to load some new
219 configuration, it is partially rolled back to defaults (the rollback
220 happens, but instead of removing the journal entry, another journal
221 entry is added for the rollback). If the loading succeeds, the two
222 journal entries are removed and a new one, for the new configuration,
223 is added. If it fails, the first one is replayed and the rollback
229 Creating custom parsers
230 ~~~~~~~~~~~~~~~~~~~~~~~
232 If you need to parse some data type the configuration system can't
233 handle, you can write your own parser. But before you start, you
234 should know a few things.
236 The parser needs to support <<journal,journaling>>. To accomplish that,
237 you have to use the <<alloc,configuration mempool>> for memory allocation.
239 Now, you need a function with the same signature as
240 <<type_cf_parser1,`cf_parser1`>>. Parse the first parameter (the
241 string) and store the data in the second parameter. You may want to
242 write a dumper function, with signature of
243 <<type_cf_dumper1,`cf_dumper1`>> (needed for debug dumps).
245 Fill in a structure <<struct_cf_user_type,cf_user_type>> and use the
246 new data type in your configuration description with
247 <<def_CF_USER,`CF_USER`>> macro as its @t parameter.
249 You do not need to call @cf_journal_block() on the variable you store
250 the result. It is true you change it, but it was stored to journal
251 before your parser function was called.
257 The configuration system supports hooks. They are used to initialize the
258 configuration (if simple default value of variable is not enough) and
259 to check the sanity of loaded data.
261 Each hook is of type <<type_cf_hook,`cf_hook`>> and you can include
262 them in configuration description using <<def_CF_INIT,`CF_INIT`>> and
263 <<def_CF_COMMIT,`CF_COMMIT`>> macros.
265 The hooks should follow similar guidelines as custom parsers (well,
266 init hooks do not need to call @cf_journal_block()) to support
267 journaling. If you change nothing in the commit hook, you do not need
268 to care about the journaling either.
270 You may use the return value to inform about errors. Just return the
271 error message, or NULL if everything went well.
273 Another similar function is a copy function. It is very similar to a
274 hook and is used when the item is copied and is too complicated to use
275 simple memcpy(). Its type is <<type_cf_copier,`cf_copier`>> and is
276 specified by the <<def_CF_COPY,`CF_COPY`>> macro. It's return value is
277 the same as the one of a hook.
283 Use this file if you want define a configuration section, request
284 loading of some variables or create new item type.
292 This header contains routines for parsing command line arguments and
293 loading the configuration.