Configuration and command line parser
=====================================

Libucw contains a parser for configuration files described in
<<config:>>.

The principle is you specify the structure of the configuration file,
the section names, variable names and types and your C variables that
are assigned to them. Then you run the parser and it fills your
variables with the values from the configuration file.

It is modular. It means you do not have to write all configuration at
the same place, you just declare the parts you need locally and do not
care about the other parts.

The command line parser has the same interface as unix getopt_long,
but handles setting of configuration files and configuration values
from command line.

- <<example,Example>>
  * <<ex_structure,The structure>>
  * <<ex_load,Loading>>
- <<conf_h,ucw/conf.h>>
  * <<conf_types,Data types>>
  * <<conf_macros,Convenience macros>>
  * <<alloc,Memory allocation>>
  * <<journal,Undo journal>>
  * <<bparser,Parsers for basic types>>

[[example]]
Example
-------

[[ex_cfile]]
Let's say you have configuration file with this content and want to
load it:

  HelloWorld {
    Text	"Hello planet"
    Count	3
  }

[[ex_structure]]
The structure
~~~~~~~~~~~~~
First, you declare the structure and let the configuration parser know
it exists.

  #include <ucw/lib.h>
  #include <ucw/conf.h>

  static char *hw_text = "Hello world";
  static int hw_count = 1;
  static int hw_wait_answer = 0;

  static struct cf_section hw_config = {
    CF_ITEMS {
      CF_STRING("Text", &hw_text),
      CF_INT("Count", &hw_count),
      CF_INT("WaitAnswer", &hw_wait_answer),
      CF_END
    }
  };

  static void CONSTRUCTOR hw_init(void) {
    cf_declare_section("HelloWorld", &hw_config, 0);
  }

The variables are used to store the loaded values. Their initial
values work as default, if nothing else is loaded. The hw_config()
structure assigns the variables to configuration names. The hw_init()
function (because of the `CONSTRUCTOR` macro) is run before main()
is called and it plugs in the whole section to the parser.

You can plug in as many configuration sections as you like, from
various places across your code.

[[ex_load]]
Loading of the values
~~~~~~~~~~~~~~~~~~~~~
You need to parse the command line arguments and load the
configuration. You can do it in a similar way to this example.

  #include <ucw/lib.h>
  #include <ucw/conf.h>
  #include <ucw/getopt.h>

  static byte short_opts[] = CF_SHORT_OPTS "v";
  static struct option long_opts[] = {
    CF_LONG_OPTS
    { "verbose", 0, 0, 'v' },
    { NULL, 0, 0, 0 }
  };

  int verbose;

  int main(int argc, char *argv[]) {
    cf_def_file = "default.cf";
    int opt;
    while((opt = cf_getopt(argc, argv, short_opts, long_opts, NULL)) >= 0)
      switch(opt) {
	case 'v': verbose = 1; break;
	default: fprintf("Unknown option %c\n", opt); return 1;
      }

The `short_opts` and `long_opts` variables describe the command line
arguments. Notice the `CF_SHORT_OPTS` and `CF_LONG_OPTS` macros. They
add options for the configuration parser. These options are handled
internally by @cf_getopt(). It loads the configuration before it starts
giving you your program's options.

See documentation of unix getopt_long() function.

[[conf_h]]
ucw/conf.h
----------

Use this file if you want define a configuration section, request
loading of some variables or create new item type.

!!ucw/conf.h