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.
24 OPT_CL_END, // end of list
25 OPT_CL_BOOL, // boolean value
26 OPT_CL_STATIC, // static value
27 OPT_CL_SWITCH, // lookup/switch
28 OPT_CL_INC, // incremental value
29 OPT_CL_CALL, // call a function
30 OPT_CL_USER, // user defined value
31 OPT_CL_SECTION, // subsection
32 OPT_CL_HELP, // help line
35 typedef void opt_custom_function(const char ** param);
39 const char letter; // short-op
40 const char * name; // long-op
41 void * ptr; // where to save
42 const char * help; // description in --help
44 struct opt_section * section; // subsection for OPT_SECTION
45 int value; // value for OPT_SWITCH
46 const char * help2; // second value for OPT_HELP2
47 int (* call)(const char ** param); // function to call for OPT_CALL
48 struct cf_user_type * utype; // specification of the user-defined 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_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
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 }
96 * Flags for the preceeding calls
97 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
100 #define OPT_REQUIRED 0x1 /** Argument must appear at the command line **/
101 #define OPT_REQUIRED_VALUE 0x2 /** Argument must have a value **/
102 #define OPT_NO_VALUE 0x4 /** Argument must have no value **/
103 #define OPT_MAYBE_VALUE 0x8 /** Argument may have a value **/
104 #define OPT_VALUE_FLAGS (OPT_REQUIRED_VALUE | OPT_NO_VALUE | OPT_MAYBE_VALUE)
105 #define OPT_DECREMENT 0x10 /** Reversing the effect of OPT_INC **/
106 #define OPT_SINGLE 0x20 /** Argument must appear at most once **/
107 #define OPT_NO_HELP 0x40 /** Omit this line from help **/
110 * Value flags defaults
111 * ~~~~~~~~~~~~~~~~~~~~
113 * OPT_NO_VALUE for OPT_BOOL, OPT_SWITCH and OPT_INC
114 * OPT_MAYBE_VALUE for OPT_STRING, OPT_UNS, OPT_INT
115 * Some of the value flags (OPT_NO_VALUE, OPT_MAYBE_VALUE, OPT_REQUIRED_VALUE)
116 * must be specified for OPT_CALL and OPT_USER.
119 static uns opt_default_value_flags[] = {
120 [OPT_CL_BOOL] = OPT_NO_VALUE,
121 [OPT_CL_STATIC] = OPT_MAYBE_VALUE,
122 [OPT_CL_SWITCH] = OPT_NO_VALUE,
123 [OPT_CL_INC] = OPT_NO_VALUE,
126 [OPT_CL_SECTION] = 0,
130 extern struct opt_section * opt_section_root;
131 void opt_help_noexit_internal(struct opt_section * help);
133 static void opt_help_noexit(void) {
134 opt_help_noexit_internal(opt_section_root);
137 static void opt_usage_noexit(void) {
138 fprintf(stderr, "Run with argument --help for more information.\n");
141 static int opt_show_help_internal(const char ** param UNUSED) {
146 static void opt_help(void) {
151 static void opt_usage(void) {
157 * Init the opt engine.
159 void opt_init(struct opt_section * options);
162 * Parse all the arguments.
163 * Returns the number of positional arguments and an array of them in @posargs.
165 int opt_parse(char ** argv, char *** posargs);
168 * Parse all the arguments until first positional argument is found.
169 * Returns the position of that argument in argv.
170 * On next call of this function, start from the next item in argv.
171 * Iterate this function to get all the positional arguments.
173 int opt_get(char ** argv);