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