From 0db6e10eac28f38bfc3b325b13ad95107c58ce1e Mon Sep 17 00:00:00 2001 From: Martin Mares Date: Tue, 28 Jan 2014 00:24:27 +0100 Subject: [PATCH] Opt: Documented opt and its interaction with conf --- ucw/doc/conf.txt | 115 +++++++++----- ucw/doc/lists.txt | 3 + ucw/doc/opt.txt | 74 ++++++++- ucw/doc/relnotes.txt | 3 + ucw/opt-test.c | 4 +- ucw/opt.c | 9 -- ucw/opt.h | 365 ++++++++++++++++++++++++++++++------------- 7 files changed, 404 insertions(+), 169 deletions(-) diff --git a/ucw/doc/conf.txt b/ucw/doc/conf.txt index 257447c0..43f838ec 100644 --- a/ucw/doc/conf.txt +++ b/ucw/doc/conf.txt @@ -1,5 +1,5 @@ -Configuration and command line parser -===================================== +Configuration parser +==================== Libucw contains a parser for configuration files. The syntax of the configuration files is described in <>, here we explain the @@ -14,13 +14,9 @@ The descriptions are modular. The configuration can be split to sections, each section declared at a separate place. You can also define your own data types. -There is also a simple wrapper around getopt_long(), which processes -options related to selection of a configuration file, overriding of -configuration variables and loading of the default configuration. - - <> * <> - * <> + * <> - <> * <> * <> @@ -38,7 +34,8 @@ configuration variables and loading of the default configuration. * <> * <> - <> - * <> + * <> (obsolete) + * <> (obsolete) [[example]] Example @@ -94,44 +91,35 @@ You can plug in as many configuration sections as you like, from various places across your code. [[ex_load]] -Loading of the values +Loading configuration ~~~~~~~~~~~~~~~~~~~~~ -Suppose you need to parse the command line arguments and load the -configuration. Then @cf_getopt() is there for you: it works like -the traditional @getopt_long() from the C library, but it also handles -configuration files. +You can load the configuration explicitly by calling @cf_load(). +That can be convenient when writing a library, but in normal programs, +you can ask the <> to handle it for you. - #include - #include - #include +A typical example follows, please see the <> for details. - static char short_opts[] = CF_SHORT_OPTS "v"; - static struct option long_opts[] = { - CF_LONG_OPTS - { "verbose", 0, 0, 'v' }, - { NULL, 0, 0, 0 } + #include + #include + + static struct opt_section options = { + OPT_ITEMS { + // More options can be specified here + OPT_HELP("Configuration options:"), + OPT_CONF_OPTIONS, + OPT_END + } }; - - static int verbose; - - int main(int argc, char *argv[]) { + + 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; - } + opt_parse(&options, argv+1); + // Configuration file is already loaded here + return 0; } -The `short_opts` and `long_opts` variables describe the command line -arguments. Notice the `CF_SHORT_OPTS` and `CF_LONG_OPTS` macros. They -add the `-S` and `-C` options for the configuration parser as described -in <>. These options are handled internally by @cf_getopt(). - -You can rely on the configuration files having been loaded before the -first of your program's options is parsed. - [[deep]] Getting deeper -------------- @@ -181,14 +169,14 @@ If you want dynamic array of strings, you would use: }; *Lists*:: - Linked lists based on <>. You provide description + Linked lists based on <>. You provide description of single node and pointer to the - <> variable. All the nodes will + <> variable. All the nodes will be created dynamically and put there. + -First element of your structure must be <>. +First element of your structure must be <>. + -The first example is list of strings and uses <>: + static struct clist list; @@ -293,4 +281,45 @@ ucw/getopt.h This header contains routines for parsing command line arguments and loading the default configuration. +In new programs, please consider using the new <> +instead. The getopt interface is already considered obsolete and may +be removed in the future. + !!ucw/getopt.h + +Example +~~~~~~~ +Typically, @cf_getopt() is used as follows: it works like +the traditional @getopt_long() from the C library, but it also handles +configuration files. + + #include + #include + #include + + static char short_opts[] = CF_SHORT_OPTS "v"; + static struct option long_opts[] = { + CF_LONG_OPTS + { "verbose", 0, 0, 'v' }, + { NULL, 0, 0, 0 } + }; + + static 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 the `-S` and `-C` options for the configuration parser as described +in <>. These options are handled internally by @cf_getopt(). + +You can rely on the configuration files having been loaded before the +first of your program's options is parsed. diff --git a/ucw/doc/lists.txt b/ucw/doc/lists.txt index eb9f1188..68deff6d 100644 --- a/ucw/doc/lists.txt +++ b/ucw/doc/lists.txt @@ -10,16 +10,19 @@ Linked lists can be used very simply. We define a structure as list's handle and a common header in all inserted nodes. All routines then accept and return pointers to this handle and node headers. +[[slists]] Single-linked lists ------------------- !!ucw/slists.h +[[clists]] Circular linked lists --------------------- !!ucw/clists.h +[[simple_lists]] Circular linked lists of simple items ------------------------------------- diff --git a/ucw/doc/opt.txt b/ucw/doc/opt.txt index 3cb2592f..e5e5900c 100644 --- a/ucw/doc/opt.txt +++ b/ucw/doc/opt.txt @@ -1,13 +1,81 @@ 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 <>. + +- <> +- <> +- <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + * <> + +[[example]] +Example +------- +Let us start with a simple example: a program with several options and +one mandatory positional argument. + + #include + #include + + 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, "\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: + +- <> 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 <>. +- 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 <>. +- Flags further specifying behavior of the option (whether it is mandatory, + whether it carries a value, whether it can be set repeatedly, etc.). + FIXME: Reference to flags and their defaults. +- Help text, from which the help displayed to the user is constructed. + FIXME: Explain tabs and newlines. +- Extra data specific for the particular class. [[opt_h]] ucw/opt.h ----------- +--------- This header file contains the public interface of the option parser module. !!ucw/opt.h - diff --git a/ucw/doc/relnotes.txt b/ucw/doc/relnotes.txt index f589bac1..ce1a90b9 100644 --- a/ucw/doc/relnotes.txt +++ b/ucw/doc/relnotes.txt @@ -4,6 +4,9 @@ Release notes WIP --- +* A <> has been added, similar in spirit to + our <>. The <> module + has been obsoleted * `` is automatically included by ``. * *Incompatible:* The interface of the <> module was cleaned up to remove non-systematic side-effects. The `HEAP_INSERT` operation is now diff --git a/ucw/opt-test.c b/ucw/opt-test.c index 408464d6..b9bedde5 100644 --- a/ucw/opt-test.c +++ b/ucw/opt-test.c @@ -114,7 +114,7 @@ static struct opt_section water_options = { } }; -static struct opt_section help = { +static struct opt_section options = { OPT_ITEMS { OPT_HELP("A simple tea boiling console."), OPT_HELP("Usage: teapot [options] name-of-the-tea"), @@ -167,7 +167,7 @@ int main(int argc UNUSED, char ** argv) { cf_def_file = "etc/libucw"; clist_init(&black_magic); - opt_parse(&help, argv+1); + opt_parse(&options, argv+1); printf("English style: %s|", english ? "yes" : "no"); if (sugar) diff --git a/ucw/opt.c b/ucw/opt.c index c0986aa7..1a94f7c0 100644 --- a/ucw/opt.c +++ b/ucw/opt.c @@ -17,15 +17,6 @@ #include #include -/*** - * Value flags defaults - * ~~~~~~~~~~~~~~~~~~~~ - * - * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC - * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT - * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE) - * must be specified for OPT_CALL and OPT_USER. - ***/ static uns opt_default_value_flags[] = { [OPT_CL_BOOL] = OPT_NO_VALUE, [OPT_CL_STATIC] = OPT_MAYBE_VALUE, diff --git a/ucw/opt.h b/ucw/opt.h index ae0b53d0..f376a811 100644 --- a/ucw/opt.h +++ b/ucw/opt.h @@ -33,94 +33,277 @@ #define OPT_EXIT_BAD_ARGS 2 /*** - * [[opt]] + * [[classes]] + * Option classes + * -------------- + * + * Each option belongs to one of the following classes, which define + * the overall behavior of the option. In most cases, the classes + * are set automatically by <>. + * + * - `OPT_CL_END`: this is not a real option class, but a signal + * that the list of options ends. + * - `OPT_CL_BOOL`: a boolean option. If specified without an argument, + * it sets the corresponding variable to 1 (true). So does an argument of + * `1`, `y`, `yes`, or `true`. Conversely, an argument of `0`, `n`, `no`, + * or `false` sets the variable to 0 (false) and the same happens if + * the option is given as `--no-`'option' with no argument. + * - `OPT_CL_STATIC`: options of this class just take a value and store + * it in the variable. + * - `OPT_CL_SWITCH`: a multiple-choice switch, which sets the variable + * to a fixed value provided in option definition. + * - `OPT_CL_INC`: increments the variable (or decrements, if the + * `OPT_NEGATIVE` flag is set). + * - `OPT_CL_CALL`: instead of setting a variable, call a function + * and pass the value of the option to it. + * - `OPT_CL_USER`: like `OPT_CL_STATIC`, but with user-defined value + * syntax, specified as <>. + * - `OPT_CL_SECTION`: not a real option, but an instruction to insert + * contents of another list of options. + * - `OPT_CL_HELP`: no option, just print a help text. + * - `OPT_CL_HOOK`: no option, but a definition of a hook. (FIXME) ***/ enum opt_class { - OPT_CL_END, // end of list - OPT_CL_BOOL, // boolean value - OPT_CL_STATIC, // static value - OPT_CL_SWITCH, // lookup/switch - OPT_CL_INC, // incremental value - OPT_CL_CALL, // call a function - OPT_CL_USER, // user defined value - OPT_CL_SECTION, // subsection - OPT_CL_HELP, // help line - OPT_CL_HOOK, // hook + OPT_CL_END, + OPT_CL_BOOL, + OPT_CL_STATIC, + OPT_CL_SWITCH, + OPT_CL_INC, + OPT_CL_CALL, + OPT_CL_USER, + OPT_CL_SECTION, + OPT_CL_HELP, + OPT_CL_HOOK, +}; + +/*** + * [[opt_item]] + * Option definitions + * ------------------ + * + * The list of options is represented by `struct opt_section`, which points to + * a sequence of `struct opt_item`s. + * + * These structures are seldom used directly -- instead, they are produced + * by <>. + ***/ + +/** A section of option list. **/ +struct opt_section { + struct opt_item * opt; }; -struct opt_section; +/** A definition of a single option item. **/ struct opt_item { - const char * name; // long-op - int letter; // short-op - void * ptr; // where to save + const char * name; // long name (NULL if none) + int letter; // short name (0 if none) + void * ptr; // variable to store the value to const char * help; // description in --help union opt_union { - struct opt_section * section; // subsection for OPT_SECTION - int value; // value for OPT_SWITCH - void (* call)(struct opt_item * opt, const char * value, void * data); // function to call for OPT_CALL - void (* hook)(struct opt_item * opt, uns event, const char * value, void * data); // function to call for OPT_CL_HOOK - struct cf_user_type * utype; // specification of the user-defined type + struct opt_section * section; // subsection for OPT_CL_SECTION + int value; // value for OPT_CL_SWITCH + void (* call)(struct opt_item * opt, const char * value, void * data); // function to call for OPT_CL_CALL + void (* hook)(struct opt_item * opt, uns event, const char * value, void * data); // function to call for OPT_CL_HOOK + struct cf_user_type * utype; // specification of the user-defined type for OPT_CL_USER } u; - u16 flags; + u16 flags; // as defined below (for hooks, event mask is stored instead) byte cls; // enum opt_class byte type; // enum cf_type }; -struct opt_section { - struct opt_item * opt; -}; +/*** + * [[flags]] + * Option flags + * ------------ + * + * Each option can specify a combination of the following flags. + ***/ + +#define OPT_REQUIRED 0x1 /** The option must be always present. **/ +#define OPT_REQUIRED_VALUE 0x2 /** The option must have a value. **/ +#define OPT_NO_VALUE 0x4 /** The option must have no value. **/ +#define OPT_MAYBE_VALUE 0x8 /** The option may have a value. **/ +#define OPT_NEGATIVE 0x10 /** Reversing the effect of OPT_INC or saving @false into OPT_BOOL. **/ +#define OPT_NO_HELP 0x20 /** Exclude this option from the help. **/ +#define OPT_LAST_ARG 0x40 /** Stop processing arguments after this line. **/ +#define OPT_SINGLE 0x100 /** The option must appear at most once. **/ +#define OPT_MULTIPLE 0x200 /** The option may appear multiple times; will save all the values into a simple list. **/ +#define OPT_SEEN_AS_LONG 0x400 // Used internally to signal that we currently process the long form of the option +#define OPT_BEFORE_CONFIG 0x800 /** The option may appear before a config file is loaded. **/ +#define OPT_INTERNAL 0x4000 // Used internally to ask for passing of struct opt_context to OPT_CALL -#define OPT_ITEMS .opt = ( struct opt_item[] ) /** List of sub-items. **/ +/** + * If none of these flags are specified, a default is chosen automatically + * according to option class: + * + * - `OPT_MAYBE_VALUE` for `OPT_CL_STATIC` + * - `OPT_NO_VALUE` for `OPT_CL_BOOL`, `OPT_CL_SWITCH` and `OPT_CL_INC` + * - An error is reported in all other cases. + **/ +#define OPT_VALUE_FLAGS (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE) /*** - * Sub-items to be enclosed in OPT_ITEMS { } list - * ---------------------------------------------- - * - * OPT_HELP_OPTION declares --help and prints a line about that - * OPT_HELP prints a line into help - * OPT_BOOL declares boolean option with an auto-negation (--sth and --no-sth). It's also possible to write --sth=y/yes/true/1/n/no/false/0. - * OPT_STRING, OPT_UNS, OPT_INT declare simple string/uns/int option - * OPT_SWITCH declares one choice of a switch statement; these have common target and different `value`s; last wins unless OPT_SINGLE is set; - * parser fails if it matches an OPT_SWITCH with OPT_SINGLE set and also target set. - * Target must be of signed integer type; it is set to -1 if no switch appears at the command-line. - * OPT_CALL calls the given function with an argument, giving also the opt_item structure and some custom data. - * OPT_HOOK is called at the specified place: before option parsing, before value parsing and after value parsing as specified in @flags; - * OPT_HOOK_BEFORE_ARG gets @opt and @value set to NULL; - * OPT_HOOK_BEFORE_VALUE gets both @opt and @value set. - * OPT_HOOK_AFTER_VALUE gets both @opt and @value set. - * OPT_USER declares a custom type of value defined by the given @cf_user_type in @ttype - * OPT_INC declares an incremental value like -v/--verbose - * OPT_SECTION declares a subsection + * [[macros]] + * Macros for declaration of options + * --------------------------------- * + * In most cases, option definitions are built using these macros. ***/ -#define OPT_HELP_OPTION OPT_CALL(0, "help", opt_handle_help, NULL, OPT_BEFORE_CONFIG | OPT_INTERNAL | OPT_NO_VALUE, "\tShow this help") +/** Used inside `struct opt_section` to start a list of items. **/ +#define OPT_ITEMS .opt = ( struct opt_item[] ) + +/** No option, just a piece of help text. **/ #define OPT_HELP(line) { .help = line, .cls = OPT_CL_HELP } + +/** Standard `--help` option. **/ +#define OPT_HELP_OPTION OPT_CALL(0, "help", opt_handle_help, NULL, OPT_BEFORE_CONFIG | OPT_INTERNAL | OPT_NO_VALUE, "\tShow this help") + +/** Boolean option. @target should be a variable of type `int`. **/ #define OPT_BOOL(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_BOOL, .type = CT_INT } + +/** String option. @target should be a variable of type `char *`. **/ #define OPT_STRING(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_STRING } -// FIXME: U64 and DOUBLE are not described in the comment above -#define OPT_U64(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_U64 } + +// FIXME: Check that the target is of the right type (likewise in other statically typed options) +/** Ordinary integer option. @target should be a variable of type `int`. **/ #define OPT_INT(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_INT } + +/** 64-bit integer option. @target should be a variable of type `u64`. **/ +#define OPT_U64(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_U64 } + +/** Floating-point option. @target should be a variable of type `double`. **/ #define OPT_DOUBLE(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_DOUBLE } -// FIXME: Does IP deserve a basic type? Wouldn't a pre-defined user type be better? -// Especially, this would provide an easy extension for IPv6. + +/** IP address option, currently IPv4 only. @target should be a variable of type `u32`. **/ #define OPT_IP(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_IP } -// FIXME: Semantics not clear from the description above + +/** Switch option. @target should be a variable of type `int` and it will be set to the value @val. **/ #define OPT_SWITCH(shortopt, longopt, target, val, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .help = desc, .flags = fl, .cls = OPT_CL_SWITCH, .type = CT_LOOKUP, .u.value = val } + +/** Incrementing option. @target should be a variable of type `int`. **/ +#define OPT_INC(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .flags = fl, .help = desc, .cls = OPT_CL_INC, .type = CT_INT } + +/** + * When this option appears, call the function @fn with parameters @item, @value, @data, + * where @item points to the <> of this option, + * @value contains the current argument of the option (NULL if there is none), + * and @data is specified here. + **/ #define OPT_CALL(shortopt, longopt, fn, data, fl, desc) { .letter = shortopt, .name = longopt, .ptr = data, .help = desc, .u.call = fn, .flags = fl, .cls = OPT_CL_CALL, .type = CT_USER } + +/** + * An option with user-defined syntax. @ttype is a <> + * describing the syntax, @target is a variable of the corresponding type. + **/ #define OPT_USER(shortopt, longopt, target, ttype, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .u.utype = &ttype, .flags = fl, .help = desc, .cls = OPT_CL_USER, .type = CT_USER } -// FIXME: Check that the target is of the right type (likewise in other statically typed options) -#define OPT_INC(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = &target, .flags = fl, .help = desc, .cls = OPT_CL_INC, .type = CT_INT } + +/** A sub-section. **/ #define OPT_SECTION(sec) { .cls = OPT_CL_SECTION, .u.section = &sec } + +/** Declares a <> to call upon any event from the specified set. **/ #define OPT_HOOK(fn, data, events) { .cls = OPT_CL_HOOK, .u.hook = fn, .flags = events, .ptr = data } + +/** A terminator signalling the end of the option list. **/ #define OPT_END { .cls = OPT_CL_END } /*** - * UCW Conf options - * ~~~~~~~~~~~~~~~~ + * [[positional]] + * Positional arguments + * -------------------- + * + * In addition to short and long options, the parser can also process 'positional + * arguments', which don't start with a dash and whose meaning depends solely on + * their position. * - * OPT_CONF_OPTIONS declares -C and -S as described in @getopt.h + * Positional arguments are declared as options with short name `OPT_POSITIONAL(n)` + * (where `n` is the position of the argument, starting with 1) and long name + * NULL. To accept an arbitrary number of positional arguments, use + * `OPT_POSITIONAL_TAIL` instead, which matches all arguments, for which no + * `OPT_POSITIONAL` is defined. (In the latter case, you probably want to define + * the argument as `OPT_MULTIPLE` or `OPT_CALL`, so that the values do not + * overwrite each other.) + * + * Options and positional arguments can be mixed arbitrarily. When a `--` appears + * as an argument, it is understood as a signal that all other arguments are + * positional. + * + * `OPT_REQUIRED` can be used with positional arguments, but all required arguments + * must come before the non-required ones. When `OPT_POSITIONAL_TAIL` is declared + * required, it means that it must match at least once. + * + * Ordering of positional arguments within the list of options need not match + * their positions. Holes in position numbering are inadvisable. + ***/ + +#define OPT_POSITIONAL(n) (OPT_POSITIONAL_TAIL+(n)) +#define OPT_POSITIONAL_TAIL 128 + +/*** + * [[func]] + * Functions + * --------- + ***/ + +/** + * Parse all arguments, given in a NULL-terminated array of strings. + * + * Typically, this is called from `main(argc, argv)` as `opt_parse(options, argv+1)`, + * skipping the 0th argument, which contains program name. + * + * Returns the number of arguments used (which need not be all of them + * if `OPT_LAST_ARG` was encountered). + * + * The argument array is left untouched. + * However, option values are not necessarily copied, the variables + * set by the parser may point to the argument array. + **/ +int opt_parse(const struct opt_section * options, char ** argv); + +/** + * Report parsing failure, suggest `--help`, and abort the program with + * exit code 2. + **/ +void opt_failure(const char * mesg, ...) FORMAT_CHECK(printf,1,2) NONRET; + +void opt_help(const struct opt_section * sec); +void opt_handle_help(struct opt_item * opt, const char * value, void * data); + +/*** + * [[conf]] + * Cooperating with config file parser + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * + * Parsing of command-line options and configuration files are usually + * intertwined in a somewhat tricky way. We want to provide command-line + * options that control the name of the configuration file, or possibly to + * override configuration settings from the command line. On the other hand, + * regular command-line options can refer to values loaded from the + * program's configuration. + * + * To achieve this goal, the option parser is able to cooperate with the + * config file parser. This is enabled by listing the `OPT_CONF_OPTIONS` + * macro in the list of command-line options. + * + * The following options are defined for you: + * + * - `-C` (`--config`) to load a specific configuration file. This option + * suppresses loading of the default configuration, but it can be given + * multiple times to merge settings from several files. + * + * - `-S` (`--set`) to include a part of configuration inline. For example, + * you can use `-Ssection.item=value` to change a single configuration item. + * + * - `--dumpconfig` to dump the configuration to standard output and exit. + * (This is available only if the program is compiled with `CONFIG_UCW_DEBUG`.) + * + * The default configuration file (as specified by <>) is loaded + * as soon as the first option different from `-C` is encountered, unless + * a different file has been already loaded. For this reason, `-C` must be + * the very first argument given to the program. + * + * This interface supersedes <>. ***/ #ifdef CONFIG_UCW_DEBUG @@ -141,78 +324,36 @@ void opt_conf_hook_internal(struct opt_item * opt, uns event, const char * value // XXX: This is duplicated with , but that one will hopefully go away one day. /** - * The default config (as set by `CONFIG_UCW_DEFAULT_CONFIG`) or NULL if already loaded. - * You can set it to something else manually. + * The name of the default configuration file (NULL if configuration has been + * already loaded). It is initialized to `CONFIG_UCW_DEFAULT_CONFIG`, but you + * usually want to replace it by your own config file. */ extern char *cf_def_file; /** * Name of environment variable that can override what configuration is loaded. - * Defaults to `CONFIG_UCW_ENV_VAR_CONFIG`. + * Defaults to the value of the `CONFIG_UCW_ENV_VAR_CONFIG` compile-time option. **/ extern char *cf_env_file; /*** - * Predefined shortopt arguments - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - * - * for the preceding calls if positional args wanted. - * Arguments are processed in the order of the numbers given to them. There must be first - * the args with OPT_REQUIRED (see below) and after them the args without OPT_REQUIRED, no mixing. - * You may define a catch-all option as OPT_POSITIONAL_TAIL. After this, no positional arg is allowed. - * You may shuffle the positional arguments in any way in the opt sections but the numbering must obey - * the rules given here. - ***/ -// FIXME: The previous paragraph is almost incomprehensible - -// FIXME: Is numbering from 1 natural here? -// FIXME: Are there any rules for mixing of positional arguments with options? -#define OPT_POSITIONAL(n) (OPT_POSITIONAL_TAIL+(n)) -#define OPT_POSITIONAL_TAIL 128 - - -/*** - * Flags for the preceding calls - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * [[hooks]] + * Hooks + * ----- + * + * You can supply hook functions, which will be called by the parser upon various + * events. Hooks are declared as option items of class `OPT_CL_HOOK`, whose @flags + * field specifies a mask of events the hook wants to receive. + * + * Please note that the hook interface is not considered stable yet, + * so it might change in future versions of libucw. + * + * The following events are defined: ***/ -#define OPT_REQUIRED 0x1 /** Argument must appear at the command line **/ -#define OPT_REQUIRED_VALUE 0x2 /** Argument must have a value **/ -#define OPT_NO_VALUE 0x4 /** Argument must have no value **/ -#define OPT_MAYBE_VALUE 0x8 /** Argument may have a value **/ -#define OPT_VALUE_FLAGS (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE) -#define OPT_NEGATIVE 0x10 /** Reversing the effect of OPT_INC or saving @false into OPT_BOOL **/ -#define OPT_NO_HELP 0x20 /** Omit this line from help **/ -#define OPT_LAST_ARG 0x40 /** Stop processing argv after this line **/ -#define OPT_SINGLE 0x100 /** Argument must appear at most once **/ -#define OPT_MULTIPLE 0x200 /** Argument may appear any time; will save all the values into a simple list **/ -#define OPT_SEEN_AS_LONG 0x400 // Used internally to signal that we currently process the long form of the option -#define OPT_BEFORE_CONFIG 0x800 /** Argument may appear before config file is loaded **/ -#define OPT_INTERNAL 0x4000 // Used internally to ask for passing of struct opt_context to OPT_CALL - -// For hooks, the flags contain a combination of events. #define OPT_HOOK_BEFORE_ARG 0x1 /** Call before option parsing **/ #define OPT_HOOK_BEFORE_VALUE 0x2 /** Call before value parsing **/ #define OPT_HOOK_AFTER_VALUE 0x4 /** Call after value parsing **/ #define OPT_HOOK_FINAL 0x8 /** Call just before opt_parse() returns **/ #define OPT_HOOK_INTERNAL 0x4000 // Used internally to ask for passing of struct opt_context -void opt_failure(const char * mesg, ...) FORMAT_CHECK(printf,1,2) NONRET; -void opt_help(const struct opt_section * sec); -void opt_handle_help(struct opt_item * opt, const char * value, void * data); - -/** - * Parse all arguments, given in a NULL-terminated array of strings. - * - * Typically, this is called from `main(argc, argv)` as `opt_parse(options, argv+1)`, - * skipping the 0th argument, which contains program name. - * - * Returns the number of arguments used (which need not be all of them - * if `OPT_LAST_ARG` was encountered). - * - * The argument array is left untouched. - * However, option values are not necessarily copied, the variables - * set by the parser may point to the argument array. - **/ -int opt_parse(const struct opt_section * options, char ** argv); - #endif -- 2.39.2