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