2 * UCW Library -- Parsing of command line options
4 * (c) 2013 Jan Moskyto Matejka <mq@ucw.cz>
6 * This software may be freely distributed and used according to the terms
7 * of the GNU Lesser General Public License.
19 #define OPT_EXIT_BAD_ARGS 2
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
40 const char * name; // long-op
41 int letter; // short-op
42 void * ptr; // where to save
43 const char * help; // description in --help
45 struct opt_section * section; // subsection for OPT_SECTION
46 int value; // value for OPT_SWITCH
47 void (* call)(struct opt_item * opt, const char * value, void * data); // function to call for OPT_CALL
48 struct cf_user_type * utype; // specification of the user-defined type
51 byte cls; // enum opt_class
52 byte type; // enum cf_type
56 struct opt_item * opt;
59 #define OPT_ITEMS .opt = ( struct opt_item[] ) /** List of sub-items. **/
62 * Sub-items to be enclosed in OPT_ITEMS { } list
63 * ----------------------------------------------
65 * OPT_HELP_OPTION 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). It's also possible to write --sth=y/yes/true/1/n/no/false/0.
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 an argument, giving also the opt_item structure and some custom data.
74 * OPT_HOOK is called at the specified place: before option parsing, before value parsing and after value parsing as specified in @flags;
75 * OPT_HOOK_BEFORE_ARG gets @opt and @value set to NULL;
76 * OPT_HOOK_BEFORE_VALUE gets both @opt and @value set.
77 * OPT_HOOK_AFTER_VALUE gets both @opt and @value set.
78 * OPT_USER declares a custom type of value defined by the given @cf_user_type in @ttype
79 * OPT_INC declares an incremental value like -v/--verbose
80 * OPT_SECTION declares a subsection
84 #define OPT_HELP_OPTION OPT_CALL(0, "help", opt_show_help_internal, NULL, OPT_NO_VALUE, "Show this help")
85 #define OPT_HELP(line) { .help = line, .cls = OPT_CL_HELP }
86 #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 }
87 #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 }
88 // FIXME: U64 and DOUBLE are not described in the comment above
89 #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 }
90 #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 }
91 #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 }
92 // FIXME: Does IP deserve a basic type? Wouldn't a pre-defined user type be better?
93 // Especially, this would provide an easy extension for IPv6.
94 #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 }
95 // FIXME: Semantics not clear from the description above
96 #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 }
97 #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 }
98 #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 }
99 // FIXME: Check that the target is of the right type (likewise in other statically typed options)
100 #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 }
101 #define OPT_SECTION(sec) { .cls = OPT_CL_SECTION, .u.section = &sec }
102 #define OPT_HOOK(fn, data, fl) { .cls = OPT_CL_HOOK, .u.call = fn, .flags = OPT_NO_HELP | fl, .ptr = data }
103 #define OPT_END { .cls = OPT_CL_END }
109 * OPT_CONF_OPTIONS declares -C and -S as described in @getopt.h
112 #ifdef CONFIG_UCW_DEBUG
113 #define OPT_CONF_OPTIONS OPT_CONF_CONFIG, OPT_CONF_SET, OPT_CONF_DUMPCONFIG, OPT_CONF_HOOK
115 #define OPT_CONF_OPTIONS OPT_CONF_CONFIG, OPT_CONF_SET, OPT_CONF_HOOK
118 #define OPT_CONF_CONFIG OPT_CALL('C', "config", opt_conf_internal, NULL, OPT_REQUIRED_VALUE, "Override the default configuration file")
119 #define OPT_CONF_SET OPT_CALL('S', "set", opt_conf_internal, NULL, OPT_REQUIRED_VALUE, "Manual setting of a configuration item")
120 #define OPT_CONF_DUMPCONFIG OPT_CALL(0, "dumpconfig", opt_conf_internal, NULL, OPT_NO_VALUE, "Dump program configuration")
121 #define OPT_CONF_HOOK OPT_HOOK(opt_conf_hook_internal, NULL, OPT_HOOK_BEFORE_VALUE)
123 void opt_conf_internal(struct opt_item * opt, const char * value, void * data);
124 void opt_conf_hook_internal(struct opt_item * opt, const char * value, void * data);
126 extern int opt_parsed_count; /** How many opts have been already parsed. **/
127 extern int opt_conf_parsed_count;
130 * Predefined shortopt arguments
131 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
133 * for the preceding calls if positional args wanted.
134 * Arguments are processed in the order of the numbers given to them. There must be first
135 * the args with OPT_REQUIRED (see below) and after them the args without OPT_REQUIRED, no mixing.
136 * You may define a catch-all option as OPT_POSITIONAL_TAIL. After this, no positional arg is allowed.
137 * You may shuffle the positional arguments in any way in the opt sections but the numbering must obey
138 * the rules given here.
140 // FIXME: The previous paragraph is almost incomprehensible
142 // FIXME: Is numbering from 1 natural here?
143 // FIXME: Are there any rules for mixing of positional arguments with options?
144 #define OPT_POSITIONAL(n) (OPT_POSITIONAL_TAIL+(n))
145 #define OPT_POSITIONAL_TAIL 256
149 * Flags for the preceding calls
150 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153 #define OPT_REQUIRED 0x1 /** Argument must appear at the command line **/
154 #define OPT_REQUIRED_VALUE 0x2 /** Argument must have a value **/
155 #define OPT_NO_VALUE 0x4 /** Argument must have no value **/
156 #define OPT_MAYBE_VALUE 0x8 /** Argument may have a value **/
157 #define OPT_VALUE_FLAGS (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE)
158 #define OPT_NEGATIVE 0x10 /** Reversing the effect of OPT_INC or saving @false into OPT_BOOL **/
159 #define OPT_NO_HELP 0x20 /** Omit this line from help **/
160 #define OPT_LAST_ARG 0x40 /** Stop processing argv after this line **/
161 #define OPT_SINGLE 0x100 /** Argument must appear at most once **/
162 #define OPT_MULTIPLE 0x200 /** Argument may appear any time; will save all the values into a simple list **/
163 #define OPT_HOOK_BEFORE_ARG 0x1000 /** Call before option parsing **/
164 #define OPT_HOOK_BEFORE_VALUE 0x2000 /** Call before value parsing **/
165 #define OPT_HOOK_AFTER_VALUE 0x4000 /** Call after value parsing **/
169 * Value flags defaults
170 * ~~~~~~~~~~~~~~~~~~~~
172 * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC
173 * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT
174 * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE)
175 * must be specified for OPT_CALL and OPT_USER.
178 static uns opt_default_value_flags[] = {
179 [OPT_CL_BOOL] = OPT_NO_VALUE,
180 [OPT_CL_STATIC] = OPT_MAYBE_VALUE,
181 [OPT_CL_SWITCH] = OPT_NO_VALUE,
182 [OPT_CL_INC] = OPT_NO_VALUE,
185 [OPT_CL_SECTION] = 0,
189 extern const struct opt_section * opt_section_root;
190 void opt_help_internal(const struct opt_section * help);
192 static void opt_help(void) {
193 opt_help_internal(opt_section_root);
196 static void opt_usage(void) {
197 fprintf(stderr, "Run with argument --help for more information.\n");
200 static void opt_show_help_internal(struct opt_item * opt UNUSED, const char * value UNUSED, void * data UNUSED) {
206 * Parse all the arguments.
208 void opt_parse(const struct opt_section * options, char ** argv);
209 // FIXME: When parsing finishes (possibly due to OPT_LAST_ARG), what is guaranteed
210 // about the state of argv[]?