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