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 /***
  20  * [[opt]]
  21  * Parsing of command line options
  22  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  23  ***/
  24
  25 enum opt_class {
  26   OPT_CL_END,     // end of list
  27   OPT_CL_BOOL,    // boolean value
  28   OPT_CL_STATIC,  // static value
  29   OPT_CL_SWITCH,  // lookup/switch
  30   OPT_CL_INC,     // incremental value
  31   OPT_CL_CALL,    // call a function
  32   OPT_CL_USER,    // user defined value
  33   OPT_CL_SECTION, // subsection
  34   OPT_CL_HELP,    // help line
  35 };
  36
  37 typedef void opt_custom_function(const char ** param);
  38
  39 struct opt_section;
  40 struct opt_item {
  41   const char letter;                    // short-op
  42   const char * name;                    // long-op
  43   void * ptr;                           // where to save
  44   const char * help;                    // description in --help
  45   union opt_union {
  46     struct opt_section * section;       // subsection for OPT_SECTION
  47     int value;                          // value for OPT_SWITCH
  48     const char * help2;                 // second value for OPT_HELP2
  49     int (* call)(const char ** param);  // function to call for OPT_CALL
  50     struct cf_user_type * utype;                // specification of the user-defined type
  51   } u;
  52   short flags;
  53   enum opt_class cls;
  54   enum cf_type type;
  55 };
  56
  57 struct opt_section {
  58   struct opt_item * opt;
  59 };
  60
  61 #define OPT_ITEMS       .opt = ( struct opt_item[] )  /** List of sub-items. **/
  62
  63 /** Sub-items to be enclosed in OPT_ITEMS { } list
  64  *
  65  * OPT_SHOW_HELP declares --help and prints a line about that
  66  * OPT_HELP prints a line into help()
  67  * OPT_HELP2 prints two strings onto a line using the same tab structure as the option listing
  68  * OPT_BOOL declares boolean option with an auto-negation (--sth and --no-sth); may be changed by OPT_BOOL_SET_PREFIXES
  69  * OPT_STRING, OPT_UNS, OPT_INT declare simple string/uns/int option
  70  * OPT_SWITCH declares one choice of a switch statement; these have common target and different `value`s; last wins unless OPT_SINGLE is set;
  71  *            parser fails if it matches an OPT_SWITCH with OPT_SINGLE set and also target set.
  72  *            Target must be of signed integer type; it is set to -1 if no switch appears at the command-line.
  73  * OPT_CALL calls the given function with all the remaining command line, it returns the number of arguments to be skipped.
  74  * OPT_USER declares a custom type of value; parser is of type opt_custom_parser
  75  *                                           and returns 1 on success and 0 on failure
  76  * OPT_INC declares an incremental value like -v/--verbose
  77  * OPT_SECTION declares a subsection
  78  *
  79  * **/
  80
  81 #define OPT_SHOW_HELP OPT_CALL(0, "help", opt_show_help_internal, OPT_NO_VALUE, "Show this help")
  82 #define OPT_HELP(line) OPT_HELP2(line, NULL)
  83 #define OPT_HELP2(first, second) { .help = first, .cls = OPT_CL_HELP, .u.help2 = second }
  84 #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 }
  85 #define OPT_STRING(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = CHECK_PTR_TYPE(&target, char **), .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_STRING }
  86 #define OPT_UNS(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = CHECK_PTR_TYPE(&target, uns *), .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_INT }
  87 #define OPT_INT(shortopt, longopt, target, fl, desc) { .letter = shortopt, .name = longopt, .ptr = CHECK_PTR_TYPE(&target, int *), .help = desc, .flags = fl, .cls = OPT_CL_STATIC, .type = CT_INT }
  88 #define OPT_SWITCH(shortopt, longopt, target, val, fl, desc) { .letter = shortopt, .name = longopt, .ptr = CHECK_PTR_TYPE(&target, int *), .help = desc, .flags = fl, .cls = OPT_CL_SWITCH, .type = CT_LOOKUP, .u.value = val }
  89 #define OPT_CALL(shortopt, longopt, fn, fl, desc) { .letter = shortopt, .name = longopt, .ptr = NULL, .help = desc, .u.call = fn, .flags = fl, .cls = OPT_CL_CALL, .type = CT_USER }
  90 #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 }
  91 #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 }
  92 #define OPT_SECTION(sec) { .cls = OPT_CL_SECTION, .u.section = &sec }
  93 #define OPT_END { .cls = OPT_CL_END }
  94
  95 /** Flags for the preceeding calls **/
  96 #define OPT_REQUIRED        0x1         // Argument must appear at the command line
  97 #define OPT_REQUIRED_VALUE  0x2         // Argument must have a value
  98 #define OPT_NO_VALUE        0x4         // Argument must have no value
  99 #define OPT_MAYBE_VALUE     0x8         // Argument may have a value
 100 #define OPT_VALUE_FLAGS     (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE)
 101 #define OPT_DECREMENT       0x10        // Reversing the effect of OPT_INC
 102 #define OPT_SINGLE          0x20        // Argument must appear at most once
 103 #define OPT_NO_HELP         0x40        // Omit this line from help
 104
 105 /** Value flags defaults:
 106  * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC
 107  * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT
 108  * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE)
 109  * must be specified for OPT_CALL and OPT_USER.
 110  */
 111 static uns opt_default_value_flags[] = {
 112   [OPT_CL_BOOL] = OPT_NO_VALUE,
 113   [OPT_CL_STATIC] = OPT_MAYBE_VALUE,
 114   [OPT_CL_SWITCH] = OPT_NO_VALUE,
 115   [OPT_CL_INC] = OPT_NO_VALUE,
 116   [OPT_CL_CALL] = 0,
 117   [OPT_CL_USER] = 0,
 118   [OPT_CL_SECTION] = 0,
 119   [OPT_CL_HELP] = 0
 120 };
 121
 122 extern struct opt_section * opt_section_root;
 123 void opt_help_noexit_internal(struct opt_section * help);
 124
 125 static void opt_help_noexit(void) {
 126   opt_help_noexit_internal(opt_section_root);
 127 }
 128
 129 static void opt_usage_noexit(void) {
 130   fprintf(stderr, "Run with argument --help for more information.\n");
 131 }
 132
 133 static int opt_show_help_internal(const char ** param UNUSED) {
 134   opt_help_noexit();
 135   exit(0);
 136 }
 137
 138 static void opt_help(void) {
 139   opt_help_noexit();
 140   exit(1);
 141 }
 142
 143 static void opt_usage(void) {
 144   opt_usage_noexit();
 145   exit(1);
 146 }
 147
 148 /**
 149  * Init the opt engine.
 150  */
 151 void opt_init(struct opt_section * options);
 152
 153 /**
 154  * Parse all the arguments.
 155  * Returns the number of positional arguments and an array of them in @posargs.
 156  */
 157 int opt_parse(char ** argv, char *** posargs);
 158
 159 /**
 160  * Parse all the arguments until first positional argument is found.
 161  * Returns the position of that argument in argv.
 162  * On next call of this function, start from the next item in argv.
 163  * Iterate this function to get all the positional arguments.
 164  */
 165 int opt_get(char ** argv);
 166
 167 #endif