4 Libucw contains a parser of command-line options, more versatile and
5 easier to use than the usual `getopt()` and `getopt_long()`. It follows the
6 traditional UNIX conventions of option syntax, but the options are defined in
7 a declarative way, similar in spirit to our <<conf:,configuration file
11 - <<anatomy,Anatomy of options>>
13 * <<classes,Option classes>>
14 * <<opt_item,Option definitions>>
15 * <<flags,Option flags>>
16 * <<macros,Macros for declaration of options>>
17 * <<positional,Positional arguments>>
19 * <<conf,Cooperating with configuration file parser>>
25 Let us start with a simple example: a program with several options and
26 one mandatory positional argument.
36 static struct opt_section options = {
38 OPT_HELP("A simple tea boiling console."),
39 OPT_HELP("Usage: teapot [options] name-of-the-tea"),
43 OPT_BOOL('e', "english-style", english, 0, "\tEnglish style (with milk)"),
44 OPT_INT('s', "sugar", sugar, OPT_REQUIRED_VALUE, "<spoons>\tAmount of sugar (in teaspoons)"),
45 OPT_INC('v', "verbose", verbose, 0, "\tVerbose (the more -v, the more verbose)"),
46 OPT_STRING(OPT_POSITIONAL(1), NULL, tea_name, OPT_REQUIRED, ""),
51 int main(int argc, char **argv)
53 opt_parse(&options, argv+1);
60 Most options have the following properties:
62 - <<classes,Option class>> defining overall behavior of the option
63 - Short name: one character. Set to 0 if the option has no short form.
64 Alternatively, the short name can refer to a <<positional,positional argument>>.
65 - Long name: an arbitrary string. Set to NULL if the option has no long form.
66 - Variable, where the value of the option shall be stored, together with
67 its <<conf:enum_cf_type,data type>>.
68 - Flags further specifying behavior of the option (whether it is mandatory,
69 whether it carries a value, whether it can be set repeatedly, etc.).
70 FIXME: Reference to flags and their defaults.
71 - Help text, from which the help displayed to the user is constructed.
72 FIXME: Explain tabs and newlines.
73 - Extra data specific for the particular class.
79 This header file contains the public interface of the option parser module.