Option parser
=============
-FIXME!
+Libucw contains a parser of command-line options, more versatile and
+easier to use than the usual `getopt()` and `getopt_long()`. It follows the
+traditional UNIX conventions of option syntax, but the options are defined in
+a declarative way, similar in spirit to our <<conf:,configuration file
+parser>>.
+
+- <<example,Example>>
+- <<anatomy,Anatomy of options>>
+- <<opt_h,ucw/opt.h>>
+ * <<classes,Option classes>>
+ * <<opt_item,Option definitions>>
+ * <<flags,Option flags>>
+ * <<macros,Macros for declaration of options>>
+ * <<positional,Positional arguments>>
+ * <<func,Functions>>
+ * <<conf,Cooperating with configuration file parser>>
+ * <<hooks,Hooks>>
+
+[[example]]
+Example
+-------
+Let us start with a simple example: a program with several options and
+one mandatory positional argument.
+
+ #include <ucw/lib.h>
+ #include <ucw/opt.h>
+
+ int english;
+ int sugar;
+ int verbose;
+ char *tea_name;
+
+ static struct opt_section options = {
+ OPT_ITEMS {
+ OPT_HELP("A simple tea boiling console."),
+ OPT_HELP("Usage: teapot [options] name-of-the-tea"),
+ OPT_HELP(""),
+ OPT_HELP("Options:"),
+ OPT_HELP_OPTION,
+ OPT_BOOL('e', "english-style", english, 0, "\tEnglish style (with milk)"),
+ OPT_INT('s', "sugar", sugar, OPT_REQUIRED_VALUE, "<spoons>\tAmount of sugar (in teaspoons)"),
+ OPT_INC('v', "verbose", verbose, 0, "\tVerbose (the more -v, the more verbose)"),
+ OPT_STRING(OPT_POSITIONAL(1), NULL, tea_name, OPT_REQUIRED, ""),
+ OPT_END
+ }
+ };
+
+ int main(int argc, char **argv)
+ {
+ opt_parse(&options, argv+1);
+ return 0;
+ }
+
+[[anatomy]]
+Anatomy of options
+------------------
+Most options have the following properties:
+
+- <<classes,Option class>> defining overall behavior of the option
+- Short name: one character. Set to 0 if the option has no short form.
+ Alternatively, the short name can refer to a <<positional,positional argument>>.
+- Long name: an arbitrary string. Set to NULL if the option has no long form.
+- Variable, where the value of the option shall be stored, together with
+ its <<conf:enum_cf_type,data type>>. The type is either one of the conventional
+ types (`int`, `uint`, etc.), or a user-defined type providing its own parser
+ function via <<conf:struct_cf_user_type,`cf_user_type`>>.
+- <<flags,Flags>> further specifying behavior of the option (whether it is mandatory,
+ whether it carries a value, whether it can be set repeatedly, etc.).
+- Help text, from which the help displayed to the user is constructed.
+- Extra data specific for the particular class.
+
+The help is generated in a three-column format. The first column contains the
+short names, then come the long names, and finally option descriptions.
+The help text starts in column 2 (where it can describe the option's argument);
+you can use the tab character to advance to the next column. When a newline
+character appears, the text continues on the next line in column 1.
[[opt_h]]
ucw/opt.h
-----------
+---------
This header file contains the public interface of the option parser module.
!!ucw/opt.h
-