ucw/opt.h

   1 /*
   2  *      UCW Library -- Parsing of command line options
   3  *
   4  *      (c) 2013 Jan Moskyto Matejka <mq@ucw.cz>
   5  *
   6  *      This software may be freely distributed and used according to the terms
   7  *      of the GNU Lesser General Public License.
   8  */
   9
  10 #ifndef _UCW_OPT_H
  11 #define _UCW_OPT_H
  12
  13 #include <ucw/lib.h>
  14 #include <ucw/conf.h>
  15
  16 #include <stdlib.h>
  17 #include <stdio.h>
  18
  19 #ifdef CONFIG_UCW_CLEAN_ABI
  20 #define opt_conf_hook_internal ucw_opt_conf_hook_internal
  21 #define opt_conf_internal ucw_opt_conf_internal
  22 #define opt_conf_parsed_count ucw_opt_conf_parsed_count
  23 #define opt_help_internal ucw_opt_help_internal
  24 #define opt_parse ucw_opt_parse
  25 #define opt_parsed_count ucw_opt_parsed_count
  26 #define opt_section_root ucw_opt_section_root
  27 #endif
  28
  29 #define OPT_EXIT_BAD_ARGS 2
  30
  31 /***
  32  * [[opt]]
  33  ***/
  34
  35 enum opt_class {
  36   OPT_CL_END,     // end of list
  37   OPT_CL_BOOL,    // boolean value
  38   OPT_CL_STATIC,  // static value
  39   OPT_CL_SWITCH,  // lookup/switch
  40   OPT_CL_INC,     // incremental value
  41   OPT_CL_CALL,    // call a function
  42   OPT_CL_USER,    // user defined value
  43   OPT_CL_SECTION, // subsection
  44   OPT_CL_HELP,    // help line
  45   OPT_CL_HOOK,    // hook
  46 };
  47
  48 struct opt_section;
  49 struct opt_item {
  50   const char * name;                    // long-op
  51   int letter;                           // short-op
  52   void * ptr;                           // where to save
  53   const char * help;                    // description in --help
  54   union opt_union {
  55     struct opt_section * section;       // subsection for OPT_SECTION
  56     int value;                          // value for OPT_SWITCH
  57     void (* call)(struct opt_item * opt, const char * value, void * data);  // function to call for OPT_CALL
  58     struct cf_user_type * utype;        // specification of the user-defined type
  59   } u;
  60   u16 flags;
  61   byte cls;                             // enum opt_class
  62   byte type;                            // enum cf_type
  63 };
  64
  65 struct opt_section {
  66   struct opt_item * opt;
  67 };
  68
  69 #define OPT_ITEMS       .opt = ( struct opt_item[] )  /** List of sub-items. **/
  70
  71 /***
  72  * Sub-items to be enclosed in OPT_ITEMS { } list
  73  * ----------------------------------------------
  74  *
  75  *  OPT_HELP_OPTION declares --help and prints a line about that
  76  *  OPT_HELP prints a line into help
  77  *  OPT_HELP2 prints two strings onto a line using the same tab structure as the option listing
  78  *  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.
  79  *  OPT_STRING, OPT_UNS, OPT_INT declare simple string/uns/int option
  80  *  OPT_SWITCH declares one choice of a switch statement; these have common target and different `value`s; last wins unless OPT_SINGLE is set;
  81  *             parser fails if it matches an OPT_SWITCH with OPT_SINGLE set and also target set.
  82  *             Target must be of signed integer type; it is set to -1 if no switch appears at the command-line.
  83  *  OPT_CALL calls the given function with an argument, giving also the opt_item structure and some custom data.
  84  *  OPT_HOOK is called at the specified place: before option parsing, before value parsing and after value parsing as specified in @flags;
  85  *             OPT_HOOK_BEFORE_ARG gets @opt and @value set to NULL;
  86  *             OPT_HOOK_BEFORE_VALUE gets both @opt and @value set.
  87  *             OPT_HOOK_AFTER_VALUE gets both @opt and @value set.
  88  *  OPT_USER declares a custom type of value defined by the given @cf_user_type in @ttype
  89  *  OPT_INC declares an incremental value like -v/--verbose
  90  *  OPT_SECTION declares a subsection
  91  *
  92  ***/
  93
  94 #define OPT_HELP_OPTION OPT_CALL(0, "help", opt_show_help_internal, NULL, OPT_NO_VALUE, "Show this help")
  95 #define OPT_HELP(line) { .help = line, .cls = OPT_CL_HELP }
  96 #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 }
  97 #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 }
  98 // FIXME: U64 and DOUBLE are not described in the comment above
  99 #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 }
 100 #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 }
 101 #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 }
 102 // FIXME: Does IP deserve a basic type? Wouldn't a pre-defined user type be better?
 103 // Especially, this would provide an easy extension for IPv6.
 104 #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 }
 105 // FIXME: Semantics not clear from the description above
 106 #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 }
 107 #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 }
 108 #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 }
 109 // FIXME: Check that the target is of the right type (likewise in other statically typed options)
 110 #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 }
 111 #define OPT_SECTION(sec) { .cls = OPT_CL_SECTION, .u.section = &sec }
 112 #define OPT_HOOK(fn, data, fl) { .cls = OPT_CL_HOOK, .u.call = fn, .flags = OPT_NO_HELP | fl, .ptr = data }
 113 #define OPT_END { .cls = OPT_CL_END }
 114
 115 /***
 116  * UCW Conf options
 117  * ~~~~~~~~~~~~~~~~
 118  *
 119  * OPT_CONF_OPTIONS declares -C and -S as described in @getopt.h
 120  ***/
 121
 122 #ifdef CONFIG_UCW_DEBUG
 123 #define OPT_CONF_OPTIONS    OPT_CONF_CONFIG, OPT_CONF_SET, OPT_CONF_DUMPCONFIG, OPT_CONF_HOOK
 124 #else
 125 #define OPT_CONF_OPTIONS    OPT_CONF_CONFIG, OPT_CONF_SET, OPT_CONF_HOOK
 126 #endif
 127
 128 #define OPT_CONF_CONFIG     OPT_CALL('C', "config", opt_conf_internal, NULL, OPT_REQUIRED_VALUE, "Override the default configuration file")
 129 #define OPT_CONF_SET        OPT_CALL('S', "set", opt_conf_internal, NULL, OPT_REQUIRED_VALUE, "Manual setting of a configuration item")
 130 #define OPT_CONF_DUMPCONFIG OPT_CALL(0, "dumpconfig", opt_conf_internal, NULL, OPT_NO_VALUE, "Dump program configuration")
 131 #define OPT_CONF_HOOK       OPT_HOOK(opt_conf_hook_internal, NULL, OPT_HOOK_BEFORE_VALUE)
 132
 133 void opt_conf_internal(struct opt_item * opt, const char * value, void * data);
 134 void opt_conf_hook_internal(struct opt_item * opt, const char * value, void * data);
 135
 136 extern int opt_parsed_count;        /** How many opts have been already parsed. **/
 137 extern int opt_conf_parsed_count;
 138
 139 /***
 140  * Predefined shortopt arguments
 141  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 142  *
 143  * for the preceding calls if positional args wanted.
 144  * Arguments are processed in the order of the numbers given to them. There must be first
 145  * the args with OPT_REQUIRED (see below) and after them the args without OPT_REQUIRED, no mixing.
 146  * You may define a catch-all option as OPT_POSITIONAL_TAIL. After this, no positional arg is allowed.
 147  * You may shuffle the positional arguments in any way in the opt sections but the numbering must obey
 148  * the rules given here.
 149  ***/
 150 // FIXME: The previous paragraph is almost incomprehensible
 151
 152 // FIXME: Is numbering from 1 natural here?
 153 // FIXME: Are there any rules for mixing of positional arguments with options?
 154 #define OPT_POSITIONAL(n)   (OPT_POSITIONAL_TAIL+(n))
 155 #define OPT_POSITIONAL_TAIL 256
 156
 157
 158 /***
 159  * Flags for the preceding calls
 160  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 161  ***/
 162
 163 #define OPT_REQUIRED        0x1         /** Argument must appear at the command line **/
 164 #define OPT_REQUIRED_VALUE  0x2         /** Argument must have a value **/
 165 #define OPT_NO_VALUE        0x4         /** Argument must have no value **/
 166 #define OPT_MAYBE_VALUE     0x8         /** Argument may have a value **/
 167 #define OPT_VALUE_FLAGS     (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE)
 168 #define OPT_NEGATIVE        0x10        /** Reversing the effect of OPT_INC or saving @false into OPT_BOOL **/
 169 #define OPT_NO_HELP         0x20        /** Omit this line from help **/
 170 #define OPT_LAST_ARG        0x40        /** Stop processing argv after this line **/
 171 #define OPT_SINGLE          0x100       /** Argument must appear at most once **/
 172 #define OPT_MULTIPLE        0x200       /** Argument may appear any time; will save all the values into a simple list **/
 173 #define OPT_HOOK_BEFORE_ARG     0x1000  /** Call before option parsing **/
 174 #define OPT_HOOK_BEFORE_VALUE   0x2000  /** Call before value parsing **/
 175 #define OPT_HOOK_AFTER_VALUE    0x4000  /** Call after value parsing **/
 176
 177
 178 /***
 179  * Value flags defaults
 180  * ~~~~~~~~~~~~~~~~~~~~
 181  *
 182  * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC
 183  * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT
 184  * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE)
 185  * must be specified for OPT_CALL and OPT_USER.
 186  ***/
 187
 188 static uns opt_default_value_flags[] = {
 189   [OPT_CL_BOOL] = OPT_NO_VALUE,
 190   [OPT_CL_STATIC] = OPT_MAYBE_VALUE,
 191   [OPT_CL_SWITCH] = OPT_NO_VALUE,
 192   [OPT_CL_INC] = OPT_NO_VALUE,
 193   [OPT_CL_CALL] = 0,
 194   [OPT_CL_USER] = 0,
 195   [OPT_CL_SECTION] = 0,
 196   [OPT_CL_HELP] = 0
 197 };
 198
 199 extern const struct opt_section * opt_section_root;
 200 void opt_help_internal(const struct opt_section * help);
 201
 202 static void opt_help(void) {
 203   opt_help_internal(opt_section_root);
 204 }
 205
 206 static void opt_usage(void) {
 207   fprintf(stderr, "Run with argument --help for more information.\n");
 208 }
 209
 210 static void opt_show_help_internal(struct opt_item * opt UNUSED, const char * value UNUSED, void * data UNUSED) {
 211   opt_help();
 212   exit(0);
 213 }
 214
 215 /**
 216  * Parse all the arguments.
 217  **/
 218 void opt_parse(const struct opt_section * options, char ** argv);
 219 // FIXME: When parsing finishes (possibly due to OPT_LAST_ARG), what is guaranteed
 220 // about the state of argv[]?
 221
 222 #endif