From db476e85f3934366f8b364a19f1c4495626a9e81 Mon Sep 17 00:00:00 2001
From: Michal Vaner <vorner@ucw.cz>
Date: Sun, 14 Sep 2008 18:03:00 +0200
Subject: [PATCH] ucw docs: configuration parser (example)

Just an example how to use it. The thorough documentation of the headers
and functions to follow.
---
 ucw/doc/Makefile  |   2 +-
 ucw/doc/conf.txt  | 106 ++++++++++++++++++++++++++++++++++++++++++++++
 ucw/doc/index.txt |   1 +
 3 files changed, 108 insertions(+), 1 deletion(-)
 create mode 100644 ucw/doc/conf.txt

diff --git a/ucw/doc/Makefile b/ucw/doc/Makefile
index 75af0470..71708a77 100644
--- a/ucw/doc/Makefile
+++ b/ucw/doc/Makefile
@@ -2,7 +2,7 @@
 
 DIRS+=ucw/doc
 
-UCW_DOCS=fastbuf index basecode hash docsys
+UCW_DOCS=fastbuf index basecode hash docsys conf
 UCW_INDEX=$(o)/ucw/doc/def_index.html
 
 $(UCW_INDEX): DOC_HEAD=$(s)/ucw/doc/def_index.txt
diff --git a/ucw/doc/conf.txt b/ucw/doc/conf.txt
new file mode 100644
index 00000000..1999be1e
--- /dev/null
+++ b/ucw/doc/conf.txt
@@ -0,0 +1,106 @@
+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>>
+
+[[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.
diff --git a/ucw/doc/index.txt b/ucw/doc/index.txt
index 03b17a0b..64aca6f0 100644
--- a/ucw/doc/index.txt
+++ b/ucw/doc/index.txt
@@ -12,6 +12,7 @@ Modules
 - <<fastbuf:,Fastbufs>>
 - <<basecode:,Base64 and Base224 encoding>>
 - <<hash:,Hashing routines>>
+- <<conf:,Configuration and command line parser>>
 
 Other features
 --------------
-- 
2.39.5