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 * <<reload,Reloading configuration>>
25 * <<custom_parser,Creating custom parsers>>
27 - <<conf_h,ucw/conf.h>>
28 * <<conf_types,Data types>>
29 * <<conf_macros,Convenience macros>>
30 * <<alloc,Memory allocation>>
31 * <<journal,Undo journal>>
32 * <<bparser,Parsers for basic types>>
33 - <<getopt_h,ucw/getopt.h>>
34 * <<conf_load,Safe configuration loading>>
35 * <<conf_direct,Direct access>>
36 * <<conf_dump,Debug dumping>>
37 * <<conf_journal,Journaling control>>
38 * <<conf_getopt,Loading by cf_getopt()>>
43 If you want to just load simple configuration, this is the part you
44 want to read. This simple example should give you the overview. Look
45 into the <<conf_macros,convenience macros>> section to see list of
46 supported data types, sections, etc.
49 Let's say you have configuration file with this content and want to
60 First, you declare the structure and let the configuration parser know
66 static char *hw_text = "Hello world";
67 static int hw_count = 1;
68 static int hw_wait_answer = 0;
70 static struct cf_section hw_config = {
72 CF_STRING("Text", &hw_text),
73 CF_INT("Count", &hw_count),
74 CF_INT("WaitAnswer", &hw_wait_answer),
79 static void CONSTRUCTOR hw_init(void) {
80 cf_declare_section("HelloWorld", &hw_config, 0);
83 The variables are used to store the loaded values. Their initial
84 values work as default, if nothing else is loaded. The hw_config()
85 structure assigns the variables to configuration names. The hw_init()
86 function (because of the `CONSTRUCTOR` macro) is run before main()
87 is called and it plugs in the whole section to the parser.
89 You can plug in as many configuration sections as you like, from
90 various places across your code.
95 You need to parse the command line arguments and load the
96 configuration. You can do it in a similar way to this example.
100 #include <ucw/getopt.h>
102 static byte short_opts[] = CF_SHORT_OPTS "v";
103 static struct option long_opts[] = {
105 { "verbose", 0, 0, 'v' },
111 int main(int argc, char *argv[]) {
112 cf_def_file = "default.cf";
114 while((opt = cf_getopt(argc, argv, short_opts, long_opts, NULL)) >= 0)
116 case 'v': verbose = 1; break;
117 default: fprintf("Unknown option %c\n", opt); return 1;
120 The `short_opts` and `long_opts` variables describe the command line
121 arguments. Notice the `CF_SHORT_OPTS` and `CF_LONG_OPTS` macros. They
122 add options for the configuration parser. These options are handled
123 internally by @cf_getopt(). It loads the configuration before it starts
124 giving you your program's options.
126 See documentation of unix getopt_long() function.
132 Since the configuration system is somehow complicated, this part gives
133 you a little overview of what you can find and where.
136 Reloading configuration
137 ~~~~~~~~~~~~~~~~~~~~~~~
139 The configuration system allows you to reload configuration at
140 runtime. The new config changes the values against the default values.
141 It means, if the default value for variable `A` is `10`, the currently
142 loaded config sets it to `42` and the new config does not talk about
143 this variable, `A` will have a value of `10` after a successful load.
145 Furthermore, if the loading of a new configuration fails, the current
146 configuration is preserved.
148 All this is done with <<journal,config journaling>>. The load of the
149 first config creates a journal entry. If you try to load some new
150 configuration, it is partially rolled back to defaults (the rollback
151 happens, but instead of removing the journal entry, another journal
152 entry is added for the rollback). If the loading succeeds, the two
153 journal entries are removed and a new one, for the new configuration,
154 is added. If it fails, the first one is replayed and the rollback
160 Creating custom parsers
161 ~~~~~~~~~~~~~~~~~~~~~~~
163 If you need to parse some data type the configuration system can't
164 handle, you can write your own parser. But before you start, you
165 should know a few things.
167 The parser needs to support <<journal,journaling>>. To accomplish that,
168 you have to use the <<alloc,configuration mempool>> for memory allocation.
170 Now, you need a function with the same signature as
171 <<type_cf_parser1,`cf_parser1`>>. Parse the first parameter (the
172 string) and store the data in the second parameter. You may want to
173 write a dumper function, with signature of
174 <<type_cf_dumper1,`cf_dumper1`>> (needed for debug dumps).
176 Fill in a structure <<struct_cf_user_type,cf_user_type>> and use the
177 new data type in your configuration description with
178 <<def_CF_USER,`CF_USER`>> macro.
180 You do not need to call @cf_journal_block() on the variable you store
181 the result. It is true you change it, but it was stored to journal
182 before your parser function was called.
188 The configuration system supports hooks. They are used to initialize the
189 configuration (if simple default value of variable is not enough) and
190 to check the sanity of loaded data.
192 Each hook is of type <<type_cf_hook,`cf_hook`>> and you can include
193 them in configuration description using <<def_CF_INIT,`CF_INIT`>> and
194 <<def_CF_COMMIT,`CF_COMMIT`>> macros.
196 The hooks should follow similar guidelines as custom parsers (well,
197 init hooks do not need to call @cf_journal_block()) to support
198 journaling. If you change nothing in the commit hook, you do not need
199 to care about the journaling either.
201 You may use the return value to inform about errors. Just return the
202 error message, or NULL if everything went well.
204 Another similar function is a copy function. It is very similar to a
205 hook and is used when the item is copied and is too complicated to use
206 simple memcpy(). Its type is <<type_cf_copier,`cf_copier`>> and is
207 specified by the <<def_CF_COPY,`CF_COPY`>> macro. It's return value is
208 the same as the one of a hook.
214 Use this file if you want define a configuration section, request
215 loading of some variables or create new item type.
223 This header contains routines for parsing command line arguments and
224 loading the configuration.