ucw/doc/conf.txt

   1 Configuration and command line parser
   2 =====================================
   3
   4 Libucw contains a parser for configuration files described in
   5 <<config:>>.
   6
   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.
  11
  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.
  15
  16 The command line parser has the same interface as unix getopt_long,
  17 but handles setting of configuration files and configuration values
  18 from command line.
  19
  20 - <<example,Example>>
  21   * <<ex_structure,The structure>>
  22   * <<ex_load,Loading>>
  23
  24 [[example]]
  25 Example
  26 -------
  27
  28 [[ex_cfile]]
  29 Let's say you have configuration file with this content and want to
  30 load it:
  31
  32   HelloWorld {
  33     Text        "Hello planet"
  34     Count       3
  35   }
  36
  37 [[ex_structure]]
  38 The structure
  39 ~~~~~~~~~~~~~
  40 First, you declare the structure and let the configuration parser know
  41 it exists.
  42
  43   #include <ucw/lib.h>
  44   #include <ucw/conf.h>
  45
  46   static char *hw_text = "Hello world";
  47   static int hw_count = 1;
  48   static int hw_wait_answer = 0;
  49
  50   static struct cf_section hw_config = {
  51     CF_ITEMS {
  52       CF_STRING("Text", &hw_text),
  53       CF_INT("Count", &hw_count),
  54       CF_INT("WaitAnswer", &hw_wait_answer),
  55       CF_END
  56     }
  57   };
  58
  59   static void CONSTRUCTOR hw_init(void) {
  60     cf_declare_section("HelloWorld", &hw_config, 0);
  61   }
  62
  63 The variables are used to store the loaded values. Their initial
  64 values work as default, if nothing else is loaded. The `hw_config`
  65 structure assigns the variables to configuration names. The `hw_init`
  66 function (because of the `CONSTRUCTOR` macro) is run before `main()`
  67 is called and it plugs in the whole section to the parser.
  68
  69 You can plug in as many configuration sections as you like, from
  70 various places across your code.
  71
  72 [[ex_load]]
  73 Loading of the values
  74 ~~~~~~~~~~~~~~~~~~~~~
  75 You need to parse the command line arguments and load the
  76 configuration. You can do it in a similar way to this example.
  77
  78   #include <ucw/lib.h>
  79   #include <ucw/conf.h>
  80   #include <ucw/getopt.h>
  81
  82   static byte short_opts[] = CF_SHORT_OPTS "v";
  83   static struct option long_opts[] = {
  84     CF_LONG_OPTS
  85     { "verbose", 0, 0, 'v' },
  86     { NULL, 0, 0, 0 }
  87   };
  88
  89   int verbose;
  90
  91   int main(int argc, char *argv[]) {
  92     cf_def_file = "default.cf";
  93     int opt;
  94     while((opt = cf_getopt(argc, argv, short_opts, long_opts, NULL)) >= 0)
  95       switch(opt) {
  96         case 'v': verbose = 1; break;
  97         default: fprintf("Unknown option %c\n", opt); return 1;
  98       }
  99
 100 The `short_opts` and `long_opts` variables describe the command line
 101 arguments. Notice the `CF_SHORT_OPTS` and `CF_LONG_OPTS` macros. They
 102 add options for the configuration parser. These options are handled
 103 internally by cf_getopt(). It loads the configuration before it starts
 104 giving you your program's options.
 105
 106 See documentation of unix getopt_long() function.