1 /* Licensed under GPLv2+ - see LICENSE file for details */
4 #include <ccan/compiler/compiler.h>
5 #include <ccan/typesafe_cb/typesafe_cb.h>
12 * OPT_WITHOUT_ARG() - macro for initializing an opt_table entry (without arg)
13 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
14 * @cb: the callback when the option is found.
15 * @arg: the argument to hand to @cb.
16 * @desc: the description for opt_usage(), or opt_hidden.
18 * This is a typesafe wrapper for initializing a struct opt_table. The callback
19 * of type "char *cb(type *)", "char *cb(const type *)" or "char *cb(void *)",
20 * where "type" is the type of the @arg argument.
22 * If the @cb returns non-NULL, opt_parse() will stop parsing, use the
23 * returned string to form an error message for errlog(), free() the
24 * string (or see opt_set_alloc) and return false.
26 * Any number of equivalent short or long options can be listed in @names,
27 * separated by '|'. Short options are a single hyphen followed by a single
28 * character, long options are two hyphens followed by one or more characters.
33 #define OPT_WITHOUT_ARG(names, cb, arg, desc) \
34 { (names), OPT_CB_NOARG((cb), 0, (arg)), { (arg) }, (desc) }
37 * OPT_WITH_ARG() - macro for initializing an opt_table entry (with arg)
38 * @names: the option names eg. "--foo=<arg>", "-f" or "-f|--foo <arg>".
39 * @cb: the callback when the option is found (along with <arg>).
40 * @show: the callback to print the value in get_usage (or NULL)
41 * @arg: the argument to hand to @cb and @show
42 * @desc: the description for opt_usage(), or opt_hidden.
44 * This is a typesafe wrapper for initializing a struct opt_table. The callback
45 * is of type "char *cb(const char *, type *)",
46 * "char *cb(const char *, const type *)" or "char *cb(const char *, void *)",
47 * where "type" is the type of the @arg argument. The first argument to the
48 * @cb is the argument found on the commandline.
50 * Similarly, if @show is not NULL, it should be of type "bool show(char *,
51 * size_t len, const type *)". If there is no default, it should return false,
52 * otherwise it should write up to len bytes into the first argument and
53 * return true; unless it uses the entire len bytes it should nul-terminate that
56 * Any number of equivalent short or long options can be listed in @names,
57 * separated by '|'. Short options are a single hyphen followed by a single
58 * character, long options are two hyphens followed by one or more characters.
59 * A space or equals in @names is ignored for parsing, and only used
60 * for printing the usage.
62 * If the @cb returns non-NULL, opt_parse() will stop parsing, use the
63 * returned string to form an error message for errlog(), free() the
64 * string (or see opt_set_alloc) and return false.
69 #define OPT_WITH_ARG(name, cb, show, arg, desc) \
70 { (name), OPT_CB_ARG((cb), 0, (show), (arg)), { (arg) }, (desc) }
73 * OPT_SUBTABLE() - macro for including another table inside a table.
74 * @table: the table to include in this table.
75 * @desc: description of this subtable (for opt_usage()) or NULL.
77 #define OPT_SUBTABLE(table, desc) \
78 { (const char *)(table), OPT_SUBTABLE, \
79 sizeof(_check_is_entry(table)) ? NULL : NULL, NULL, NULL, \
83 * OPT_EARLY_WITHOUT_ARG() - macro for a early opt_table entry (without arg)
84 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
85 * @cb: the callback when the option is found.
86 * @arg: the argument to hand to @cb.
87 * @desc: the description for opt_usage(), or opt_hidden.
89 * This is the same as OPT_WITHOUT_ARG, but for opt_early_parse() instead of
93 * OPT_EARLY_WITH_ARG(), opt_early_parse()
95 #define OPT_EARLY_WITHOUT_ARG(names, cb, arg, desc) \
96 { (names), OPT_CB_NOARG((cb), OPT_EARLY, (arg)), { (arg) }, (desc) }
99 * OPT_EARLY_WITH_ARG() - macro for an early opt_table entry (with arg)
100 * @names: the option names eg. "--foo=<arg>", "-f" or "-f|--foo <arg>".
101 * @cb: the callback when the option is found (along with <arg>).
102 * @show: the callback to print the value in get_usage (or NULL)
103 * @arg: the argument to hand to @cb and @show
104 * @desc: the description for opt_usage(), or opt_hidden.
106 * This is the same as OPT_WITH_ARG, but for opt_early_parse() instead of
110 * OPT_EARLY_WITHOUT_ARG(), opt_early_parse()
112 #define OPT_EARLY_WITH_ARG(name, cb, show, arg, desc) \
113 { (name), OPT_CB_ARG((cb), OPT_EARLY, (show), (arg)), { (arg) }, (desc) }
116 * OPT_ENDTABLE - macro to create final entry in table.
118 * This must be the final element in the opt_table array.
120 #define OPT_ENDTABLE { NULL, OPT_END, NULL, NULL, NULL, { NULL }, NULL }
123 * opt_register_table - register a table of options
124 * @table: the table of options
125 * @desc: description of this subtable (for opt_usage()) or NULL.
127 * The table must be terminated by OPT_ENDTABLE.
130 * static int verbose = 0;
131 * static struct opt_table opts[] = {
132 * OPT_WITHOUT_ARG("--verbose", opt_inc_intval, &verbose,
133 * "Verbose mode (can be specified more than once)"),
134 * OPT_WITHOUT_ARG("-v", opt_inc_intval, &verbose,
135 * "Verbose mode (can be specified more than once)"),
136 * OPT_WITHOUT_ARG("--usage", opt_usage_and_exit,
137 * "args...\nA silly test program.",
138 * "Print this message."),
143 * opt_register_table(opts, NULL);
145 void opt_register_table(const struct opt_table *table, const char *desc);
148 * opt_register_noarg - register an option with no arguments
149 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
150 * @cb: the callback when the option is found.
151 * @arg: the argument to hand to @cb.
152 * @desc: the verbose description of the option (for opt_usage()), or NULL.
154 * This is used for registering a single commandline option which takes
157 * The callback is of type "char *cb(type *)", "char *cb(const type *)"
158 * or "char *cb(void *)", where "type" is the type of the @arg
161 * If the @cb returns non-NULL, opt_parse() will stop parsing, use the
162 * returned string to form an error message for errlog(), free() the
163 * string (or see opt_set_alloc) and return false.
165 #define opt_register_noarg(names, cb, arg, desc) \
166 _opt_register((names), OPT_CB_NOARG((cb), 0, (arg)), (arg), (desc))
169 * opt_register_arg - register an option with an arguments
170 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
171 * @cb: the callback when the option is found.
172 * @show: the callback to print the value in get_usage (or NULL)
173 * @arg: the argument to hand to @cb.
174 * @desc: the verbose description of the option (for opt_usage()), or NULL.
176 * This is used for registering a single commandline option which takes
179 * The callback is of type "char *cb(const char *, type *)",
180 * "char *cb(const char *, const type *)" or "char *cb(const char *, void *)",
181 * where "type" is the type of the @arg argument. The first argument to the
182 * @cb is the argument found on the commandline.
184 * If the @cb returns non-NULL, opt_parse() will stop parsing, use the
185 * returned string to form an error message for errlog(), free() the
186 * string (or see opt_set_alloc) and return false.
189 * static char *explode(const char *optarg, void *unused UNNEEDED)
191 * errx(1, "BOOM! %s", optarg);
194 * opt_register_arg("--explode|--boom", explode, NULL, NULL, opt_hidden);
196 #define opt_register_arg(names, cb, show, arg, desc) \
197 _opt_register((names), OPT_CB_ARG((cb),0,(show), (arg)), (arg), (desc))
200 * opt_register_early_noarg - register an early option with no arguments
201 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
202 * @cb: the callback when the option is found.
203 * @arg: the argument to hand to @cb.
204 * @desc: the verbose description of the option (for opt_usage()), or NULL.
206 * This is the same as opt_register_noarg(), but for opt_early_parse().
209 * opt_register_early_arg(), opt_early_parse()
211 #define opt_register_early_noarg(names, cb, arg, desc) \
212 _opt_register((names), OPT_CB_NOARG((cb), OPT_EARLY, (arg)), \
216 * opt_register_early_arg - register an early option with an arguments
217 * @names: the names of the option eg. "--foo", "-f" or "--foo|-f|--foobar".
218 * @cb: the callback when the option is found.
219 * @show: the callback to print the value in get_usage (or NULL)
220 * @arg: the argument to hand to @cb.
221 * @desc: the verbose description of the option (for opt_usage()), or NULL.
223 * This is the same as opt_register_arg(), but for opt_early_parse().
226 * opt_register_early_noarg(), opt_early_parse()
228 #define opt_register_early_arg(names, cb, show, arg, desc) \
229 _opt_register((names), OPT_CB_ARG((cb), OPT_EARLY, (show),(arg)), \
233 * opt_unregister - unregister an option.
234 * @names: the names it was registered with.
236 * This undoes opt_register[_early]_[no]arg. Returns true if the option was
237 * found, otherwise false.
239 bool opt_unregister(const char *names);
242 * opt_parse - parse arguments.
243 * @argc: pointer to argc
245 * @errlog: the function to print errors
247 * This iterates through the command line and calls callbacks registered with
248 * opt_register_arg()/opt_register_noarg() or OPT_WITHOUT_ARG/OPT_WITH_ARG
249 * entries in tables registered with opt_register_table(). As this occurs
250 * each option is removed from argc and argv.
252 * If there are unknown options, missing arguments or a callback
253 * returns false, then an error message is printed and false is
254 * returned: the erroneous option is not removed.
256 * On success, argc and argv will contain only the non-option
257 * elements, and true is returned.
260 * if (!opt_parse(&argc, argv, opt_log_stderr)) {
261 * printf("You screwed up, aborting!\n");
266 * opt_log_stderr, opt_log_stderr_exit, opt_early_parse()
268 bool opt_parse(int *argc, char *argv[], void (*errlog)(const char *fmt, ...));
271 * opt_early_parse - parse early arguments.
274 * @errlog: the function to print errors
276 * There are times when you want to parse some arguments before any other
277 * arguments; this is especially important for debugging flags (eg. --verbose)
278 * when you have complicated callbacks in option processing.
280 * You can use opt_early_parse() to only parse options registered with
281 * opt_register_earlyarg()/opt_register_early_noarg() or
282 * OPT_EARLY_WITHOUT_ARG/OPT_EARLY_WITH_ARG entries in tables registered with
283 * opt_register_table().
285 * Note that unlike opt_parse(), argc and argv are not altered.
288 * if (!opt_early_parse(argc, argv, opt_log_stderr)) {
289 * printf("You screwed up, aborting!\n");
296 bool opt_early_parse(int argc, char *argv[],
297 void (*errlog)(const char *fmt, ...));
300 * opt_early_parse_incomplete - parse early arguments, ignoring unknown ones.
303 * @errlog: the function to print errors
305 * If you have plugins, you might need to do early parsing (eg. to find the
306 * plugin directory) but you don't know what options the plugins will want.
308 * Thus, this function is just like opt_early_parse, but ignores unknown options.
311 * if (!opt_early_parse_incomplete(argc, argv, opt_log_stderr)) {
312 * printf("You screwed up, aborting!\n");
319 bool opt_early_parse_incomplete(int argc, char *argv[],
320 void (*errlog)(const char *fmt, ...));
324 * opt_free_table - reset the opt library.
326 * This frees the internal memory and returns counters to zero. Call
327 * this as the last opt function to avoid memory leaks. You can also
328 * use this function to reset option handling to its initial state (no
329 * options registered).
331 void opt_free_table(void);
334 * opt_set_alloc - set alloc/realloc/free function for opt to use.
335 * @allocfn: allocator function
336 * @reallocfn: reallocator function, ptr may be NULL, size never 0.
337 * @freefn: free function
339 * By default opt uses malloc/realloc/free, and simply crashes if they fail.
340 * You can set your own variants here.
342 void opt_set_alloc(void *(*allocfn)(size_t size),
343 void *(*reallocfn)(void *ptr, size_t size),
344 void (*freefn)(void *ptr));
347 * opt_log_stderr - print message to stderr.
348 * @fmt: printf-style format.
350 * This is a helper for opt_parse, to print errors to stderr.
353 * opt_log_stderr_exit
355 void opt_log_stderr(const char *fmt, ...);
358 * opt_log_stderr_exit - print message to stderr, then exit(1)
359 * @fmt: printf-style format.
361 * Just like opt_log_stderr, only then does exit(1). This means that
362 * when handed to opt_parse, opt_parse will never return false.
365 * // This never returns false; just exits if there's an erorr.
366 * opt_parse(&argc, argv, opt_log_stderr_exit);
368 void opt_log_stderr_exit(const char *fmt, ...);
371 * opt_invalid_argument - helper to allocate an "Invalid argument '%s'" string
372 * @arg: the argument which was invalid.
374 * This is a helper for callbacks to return a simple error string.
376 char *opt_invalid_argument(const char *arg);
379 * opt_usage - create usage message
380 * @argv0: the program name
381 * @extra: extra details to print after the initial command, or NULL.
383 * Creates a usage message, with the program name, arguments, some extra details
384 * and a table of all the options with their descriptions. If an option has
385 * description opt_hidden, it is not shown here.
387 * The table of options is formatted such that descriptions are
388 * wrapped on space boundaries. If a description has a "\n" that is
389 * left intact, and the following characters indented appropriately.
390 * If the description begins with one or more space/tab (or has a
391 * space or tab following a "\n") that line is output without wrapping.
393 * If "extra" is NULL, then the extra information is taken from any
394 * registered option which calls opt_usage_and_exit(). This avoids duplicating
395 * that string in the common case.
397 * The result should be passed to free().
400 * opt_usage_and_exit()
403 * opt_register_arg("--explode|--boom", explode, NULL, NULL,
404 * "This line will be wrapped by opt_usage\n"
405 * " But this won't because it's indented.");
407 char *opt_usage(const char *argv0, const char *extra);
410 * opt_usage_exit_fail - complain about bad usage to stderr, exit with status 1.
411 * @msg...: printf-style message to output.
413 * This prints argv[0] (if opt_parse has been called), a colon, then
414 * the message to stderr (just like errx()). Then it prints out the
415 * usage message, taken from any registered option which uses
416 * opt_usage_and_exit() as described in opt_usage(argv0, NULL) above.
417 * Then it exits with status 1.
421 * opt_usage_exit_fail("Need 5 arguments, only got %u", argc);
423 void opt_usage_exit_fail(const char *msg, ...) NORETURN;
426 * opt_hidden - string for undocumented options.
428 * This can be used as the desc parameter if you want an option not to be
429 * shown by opt_usage().
431 extern const char opt_hidden[];
433 /* Standard helpers. You can write your own: */
434 /* Sets the @b to true. */
435 char *opt_set_bool(bool *b);
436 /* Sets @b based on arg: (yes/no/true/false). */
437 char *opt_set_bool_arg(const char *arg, bool *b);
438 bool opt_show_bool(char *buf, size_t len, const bool *b);
440 char *opt_set_invbool(bool *b);
441 bool opt_show_invbool(char *buf, size_t len, const bool *b);
442 /* Sets @b based on !arg: (yes/no/true/false). */
443 char *opt_set_invbool_arg(const char *arg, bool *b);
446 char *opt_set_charp(const char *arg, char **p);
447 /* If *p is NULL, this returns false (i.e. doesn't show a default) */
448 bool opt_show_charp(char *buf, size_t len, char *const *p);
450 /* Set an integer value, various forms. Sets to 1 on arg == NULL. */
451 char *opt_set_intval(const char *arg, int *i);
452 bool opt_show_intval(char *buf, size_t len, const int *i);
453 char *opt_set_uintval(const char *arg, unsigned int *ui);
454 bool opt_show_uintval(char *buf, size_t len, const unsigned int *ui);
455 char *opt_set_longval(const char *arg, long *l);
456 bool opt_show_longval(char *buf, size_t len, const long *l);
457 char *opt_set_ulongval(const char *arg, unsigned long *ul);
458 bool opt_show_ulongval(char *buf, size_t len, const unsigned long *ul);
460 /* Set an floating point value, various forms. */
461 char *opt_set_floatval(const char *arg, float *f);
462 bool opt_show_floatval(char *buf, size_t len, const float *f);
463 char *opt_set_doubleval(const char *arg, double *d);
464 bool opt_show_doubleval(char *buf, size_t len, const double *d);
466 /* the following setting functions accept k, M, G, T, P, or E suffixes, which
467 multiplies the numeric value by the corresponding power of 1000 or 1024
468 (for the _si and _bi versions, respectively).
470 char *opt_set_intval_bi(const char *arg, int *i);
471 char *opt_set_intval_si(const char *arg, int *i);
472 char *opt_set_uintval_bi(const char *arg, unsigned int *u);
473 char *opt_set_uintval_si(const char *arg, unsigned int *u);
474 char *opt_set_longval_bi(const char *arg, long *l);
475 char *opt_set_longval_si(const char *arg, long *l);
476 char *opt_set_ulongval_bi(const char *arg, unsigned long *ul);
477 char *opt_set_ulongval_si(const char *arg, unsigned long *ul);
478 char *opt_set_longlongval_bi(const char *arg, long long *ll);
479 char *opt_set_longlongval_si(const char *arg, long long *ll);
480 char *opt_set_ulonglongval_bi(const char *arg, unsigned long long *ll);
481 char *opt_set_ulonglongval_si(const char *arg, unsigned long long *ll);
484 bool opt_show_intval_bi(char *buf, size_t len, const int *x);
485 bool opt_show_longval_bi(char *buf, size_t len, const long *x);
486 bool opt_show_longlongval_bi(char *buf, size_t len, const long long *x);
487 bool opt_show_uintval_bi(char *buf, size_t len, const unsigned int *x);
488 bool opt_show_ulongval_bi(char *buf, size_t len, const unsigned long *x);
489 bool opt_show_ulonglongval_bi(char *buf, size_t len, const unsigned long long *x);
491 bool opt_show_intval_si(char *buf, size_t len, const int *x);
492 bool opt_show_longval_si(char *buf, size_t len, const long *x);
493 bool opt_show_longlongval_si(char *buf, size_t len, const long long *x);
494 bool opt_show_uintval_si(char *buf, size_t len, const unsigned int *x);
495 bool opt_show_ulongval_si(char *buf, size_t len, const unsigned long *x);
496 bool opt_show_ulonglongval_si(char *buf, size_t len, const unsigned long long *x);
501 /* Increment and decrement. */
502 char *opt_inc_intval(int *i);
503 char *opt_dec_intval(int *i);
505 /* Display version string to stdout, exit(0). */
506 char *opt_version_and_exit(const char *version);
508 /* Display usage string to stdout, exit(0). */
509 char *opt_usage_and_exit(const char *extra);
512 * opt_find_long: low-level access to the parser
513 * @arg: string of form 'arg' or 'arg=val'.
514 * @optarg: set to `val` of present in arg, otherwise NULL. Can be NULL.
516 * Returns NULL if option is unknown. Sets *@optarg to NULL if
519 struct opt_table *opt_find_long(const char *arg, const char **optarg);
522 * opt_find_short: low-level access to the parser
523 * @arg: character representing short option
525 * Returns NULL if option is unknown.
527 struct opt_table *opt_find_short(char arg);
529 /* opt_type bits reserved for users to play with (ignored!).
530 * You can set bits in type e.g. (1<<OPT_USER_START) to (1<<OPT_USER_END)
531 * when calling _opt_register. */
532 #define OPT_USER_START 8
533 #define OPT_USER_END 15
535 /* Below here are private declarations. */
536 /* You can use this directly to build tables, but the macros will ensure
537 * consistency and type safety. */
539 OPT_NOARG = 1, /* -f|--foo */
540 OPT_HASARG = 2, /* -f arg|--foo=arg|--foo arg */
541 OPT_SUBTABLE = 4, /* Actually, longopt points to a subtable... */
542 OPT_EARLY = 8, /* Parse this from opt_early_parse() only. */
543 OPT_END = 16, /* End of the table. */
545 /* Make sure no compiler will assume we never have large
546 * values in the enum! */
547 OPT_USER_MIN = (1 << OPT_USER_START),
548 OPT_USER_MAX = (1 << OPT_USER_END),
552 const char *names; /* pipe-separated names, --longopt or -s */
554 char *(*cb)(void *arg); /* OPT_NOARG */
555 char *(*cb_arg)(const char *optarg, void *arg); /* OPT_HASARG */
556 bool (*show)(char *buf, size_t len, const void *arg);
565 /* Resolves to the four parameters for non-arg callbacks. */
566 #define OPT_CB_NOARG(cb, pre, arg) \
568 typesafe_cb_cast3(char *(*)(void *), \
569 char *(*)(typeof(*(arg))*), \
570 char *(*)(const typeof(*(arg))*), \
571 char *(*)(const void *), (cb)), \
574 /* Resolves to the four parameters for arg callbacks. */
575 #define OPT_CB_ARG(cb, pre, show, arg) \
576 OPT_HASARG|(pre), NULL, \
577 typesafe_cb_cast3(char *(*)(const char *,void *), \
578 char *(*)(const char *, typeof(*(arg))*), \
579 char *(*)(const char *, const typeof(*(arg))*), \
580 char *(*)(const char *, const void *), \
582 typesafe_cb_cast(bool (*)(char *buf, size_t, const void *), \
583 bool (*)(char *buf, size_t, const typeof(*(arg))*), (show))
585 /* Non-typesafe register function. */
586 void _opt_register(const char *names, enum opt_type type,
587 char *(*cb)(void *arg),
588 char *(*cb_arg)(const char *optarg, void *arg),
589 bool (*show)(char *buf, size_t len, const void *arg),
590 const void *arg, const char *desc);
592 /* We use this to get typechecking for OPT_SUBTABLE */
593 static inline int _check_is_entry(struct opt_table *e UNUSED) { return 0; }
595 #endif /* CCAN_OPT_H */