| 1 | parse-options API |
| 2 | ================= |
| 3 | |
| 4 | The parse-options API is used to parse and massage options in Git |
| 5 | and to provide a usage help with consistent look. |
| 6 | |
| 7 | Basics |
| 8 | ------ |
| 9 | |
| 10 | The argument vector `argv[]` may usually contain mandatory or optional |
| 11 | 'non-option arguments', e.g. a filename or a branch, 'options', and |
| 12 | 'subcommands'. |
| 13 | Options are optional arguments that start with a dash and |
| 14 | that allow to change the behavior of a command. |
| 15 | |
| 16 | * There are basically three types of options: |
| 17 | 'boolean' options, |
| 18 | options with (mandatory) 'arguments' and |
| 19 | options with 'optional arguments' |
| 20 | (i.e. a boolean option that can be adjusted). |
| 21 | |
| 22 | * There are basically two forms of options: |
| 23 | 'Short options' consist of one dash (`-`) and one alphanumeric |
| 24 | character. |
| 25 | 'Long options' begin with two dashes (`--`) and some |
| 26 | alphanumeric characters. |
| 27 | |
| 28 | * Options are case-sensitive. |
| 29 | Please define 'lower-case long options' only. |
| 30 | |
| 31 | The parse-options API allows: |
| 32 | |
| 33 | * 'stuck' and 'separate form' of options with arguments. |
| 34 | `-oArg` is stuck, `-o Arg` is separate form. |
| 35 | `--option=Arg` is stuck, `--option Arg` is separate form. |
| 36 | |
| 37 | * Long options may be 'abbreviated', as long as the abbreviation |
| 38 | is unambiguous. |
| 39 | |
| 40 | * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. |
| 41 | |
| 42 | * Boolean long options can be 'negated' (or 'unset') by prepending |
| 43 | `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, |
| 44 | options that begin with `no-` can be 'negated' by removing it. |
| 45 | Other long options can be unset (e.g., set string to NULL, set |
| 46 | integer to 0) by prepending `no-`. |
| 47 | |
| 48 | * Options and non-option arguments can clearly be separated using the `--` |
| 49 | option, e.g. `-a -b --option -- --this-is-a-file` indicates that |
| 50 | `--this-is-a-file` must not be processed as an option. |
| 51 | |
| 52 | Subcommands are special in a couple of ways: |
| 53 | |
| 54 | * Subcommands only have long form, and they have no double dash prefix, no |
| 55 | negated form, and no description, and they don't take any arguments, and |
| 56 | can't be abbreviated. |
| 57 | |
| 58 | * There must be exactly one subcommand among the arguments, or zero if the |
| 59 | command has a default operation mode. |
| 60 | |
| 61 | * All arguments following the subcommand are considered to be arguments of |
| 62 | the subcommand, and, conversely, arguments meant for the subcommand may |
| 63 | not precede the subcommand. |
| 64 | |
| 65 | Therefore, if the options array contains at least one subcommand and |
| 66 | `parse_options()` encounters the first dashless argument, it will either: |
| 67 | |
| 68 | * stop and return, if that dashless argument is a known subcommand, setting |
| 69 | `value` to the function pointer associated with that subcommand, storing |
| 70 | the name of the subcommand in argv[0], and leaving the rest of the |
| 71 | arguments unprocessed, or |
| 72 | |
| 73 | * stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL` |
| 74 | flag and that dashless argument doesn't match any subcommands, leaving |
| 75 | `value` unchanged and the rest of the arguments unprocessed, or |
| 76 | |
| 77 | * show error and usage, and abort. |
| 78 | |
| 79 | Steps to parse options |
| 80 | ---------------------- |
| 81 | |
| 82 | . `#include "parse-options.h"` |
| 83 | |
| 84 | . define a NULL-terminated |
| 85 | `static const char * const builtin_foo_usage[]` array |
| 86 | containing alternative usage strings |
| 87 | |
| 88 | . define `builtin_foo_options` array as described below |
| 89 | in section 'Data Structure'. |
| 90 | |
| 91 | . in `cmd_foo(int argc, const char **argv, const char *prefix)` |
| 92 | call |
| 93 | |
| 94 | argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); |
| 95 | + |
| 96 | `parse_options()` will filter out the processed options of `argv[]` and leave the |
| 97 | non-option arguments in `argv[]`. |
| 98 | `argc` is updated appropriately because of the assignment. |
| 99 | + |
| 100 | You can also pass NULL instead of a usage array as the fifth parameter of |
| 101 | parse_options(), to avoid displaying a help screen with usage info and |
| 102 | option list. This should only be done if necessary, e.g. to implement |
| 103 | a limited parser for only a subset of the options that needs to be run |
| 104 | before the full parser, which in turn shows the full help message. |
| 105 | + |
| 106 | Flags are the bitwise-or of: |
| 107 | |
| 108 | `PARSE_OPT_KEEP_DASHDASH`:: |
| 109 | Keep the `--` that usually separates options from |
| 110 | non-option arguments. |
| 111 | |
| 112 | `PARSE_OPT_STOP_AT_NON_OPTION`:: |
| 113 | Usually the whole argument vector is massaged and reordered. |
| 114 | Using this flag, processing is stopped at the first non-option |
| 115 | argument. |
| 116 | |
| 117 | `PARSE_OPT_KEEP_ARGV0`:: |
| 118 | Keep the first argument, which contains the program name. It's |
| 119 | removed from argv[] by default. |
| 120 | |
| 121 | `PARSE_OPT_KEEP_UNKNOWN_OPT`:: |
| 122 | Keep unknown options instead of erroring out. This doesn't |
| 123 | work for all combinations of arguments as users might expect |
| 124 | it to do. E.g. if the first argument in `--unknown --known` |
| 125 | takes a value (which we can't know), the second one is |
| 126 | mistakenly interpreted as a known option. Similarly, if |
| 127 | `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in |
| 128 | `--unknown value` will be mistakenly interpreted as a |
| 129 | non-option, not as a value belonging to the unknown option, |
| 130 | the parser early. That's why parse_options() errors out if |
| 131 | both options are set. |
| 132 | Note that non-option arguments are always kept, even without |
| 133 | this flag. |
| 134 | |
| 135 | `PARSE_OPT_NO_INTERNAL_HELP`:: |
| 136 | By default, parse_options() handles `-h`, `--help` and |
| 137 | `--help-all` internally, by showing a help screen. This option |
| 138 | turns it off and allows one to add custom handlers for these |
| 139 | options, or to just leave them unknown. |
| 140 | |
| 141 | `PARSE_OPT_SUBCOMMAND_OPTIONAL`:: |
| 142 | Don't error out when no subcommand is specified. |
| 143 | |
| 144 | Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands; |
| 145 | while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be |
| 146 | used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`. |
| 147 | |
| 148 | Data Structure |
| 149 | -------------- |
| 150 | |
| 151 | The main data structure is an array of the `option` struct, |
| 152 | say `static struct option builtin_add_options[]`. |
| 153 | |
| 154 | Option flags |
| 155 | ~~~~~~~~~~~~ |
| 156 | |
| 157 | Each option can carry flags in the `flags` field of its `option` |
| 158 | struct. These are per-option flags and are distinct from the |
| 159 | `parse_options()` flags described above; they are usually set through |
| 160 | the `OPT_*_F()` macro variants (see below) rather than by hand. They |
| 161 | are the bitwise-or of: |
| 162 | |
| 163 | `PARSE_OPT_OPTARG`:: |
| 164 | The option's argument is optional, i.e. both `--option` and |
| 165 | `--option=<value>` are accepted. |
| 166 | |
| 167 | `PARSE_OPT_NOARG`:: |
| 168 | The option takes no argument at all. Using `--option=<value>` |
| 169 | is rejected. |
| 170 | |
| 171 | `PARSE_OPT_NONEG`:: |
| 172 | Disable the automatically generated negated `--no-option` |
| 173 | form. |
| 174 | |
| 175 | `PARSE_OPT_HIDDEN`:: |
| 176 | Hide the option: it is omitted from the usage shown by |
| 177 | `git <cmd> -h`, but is still shown by `git <cmd> --help-all`. |
| 178 | The option is parsed as usual either way. This is meant for |
| 179 | deprecated, advanced or otherwise uncommon options. |
| 180 | |
| 181 | `PARSE_OPT_LASTARG_DEFAULT`:: |
| 182 | Use the default value (`defval`) when the option is used |
| 183 | without an argument, even for an option that normally requires |
| 184 | one. Only the last argument on the command line takes effect. |
| 185 | |
| 186 | `PARSE_OPT_NODASH`:: |
| 187 | The option is a single character without a leading dash, such |
| 188 | as the `+` used by some commands. |
| 189 | |
| 190 | `PARSE_OPT_LITERAL_ARGHELP`:: |
| 191 | Use the argument help string (`argh`) verbatim in the usage |
| 192 | output instead of surrounding it with `<>` or `[]`. Useful when |
| 193 | `argh` already contains a hand-formatted description. |
| 194 | |
| 195 | `PARSE_OPT_FROM_ALIAS`:: |
| 196 | Internal flag, set on options that were expanded from a |
| 197 | configured alias. It should not be set by callers. |
| 198 | |
| 199 | `PARSE_OPT_NOCOMPLETE`:: |
| 200 | Do not offer this option for completion. |
| 201 | |
| 202 | `PARSE_OPT_COMP_ARG`:: |
| 203 | The option's argument, rather than the option itself, is what |
| 204 | should be completed. |
| 205 | |
| 206 | `PARSE_OPT_CMDMODE`:: |
| 207 | The option is one of several mutually exclusive "command mode" |
| 208 | options that share the same variable. Using more than one of |
| 209 | them at once is rejected. |
| 210 | |
| 211 | Macros |
| 212 | ~~~~~~ |
| 213 | |
| 214 | There are some macros to easily define options: |
| 215 | |
| 216 | Many of the macros below have an `_F` variant (for example `OPT_BOOL_F`, |
| 217 | `OPT_STRING_F`, `OPT_INTEGER_F`, `OPT_SET_INT_F`, `OPT_BIT_F` and |
| 218 | `OPT_CALLBACK_F`) that takes an additional trailing `flags` argument. |
| 219 | That argument is the bitwise-or of the per-option flags described in the |
| 220 | "Option flags" section above; the non-`_F` macros are simply defined |
| 221 | with `flags` set to `0`. |
| 222 | |
| 223 | `OPT__ABBREV(&int_var)`:: |
| 224 | Add `--abbrev[=<n>]`. |
| 225 | |
| 226 | `OPT__COLOR(&int_var, description)`:: |
| 227 | Add `--color[=<when>]` and `--no-color`. |
| 228 | |
| 229 | `OPT__DRY_RUN(&int_var, description)`:: |
| 230 | Add `-n, --dry-run`. |
| 231 | |
| 232 | `OPT__FORCE(&int_var, description)`:: |
| 233 | Add `-f, --force`. |
| 234 | |
| 235 | `OPT__QUIET(&int_var, description)`:: |
| 236 | Add `-q, --quiet`. |
| 237 | |
| 238 | `OPT__VERBOSE(&int_var, description)`:: |
| 239 | Add `-v, --verbose`. |
| 240 | |
| 241 | `OPT_GROUP(description)`:: |
| 242 | Start an option group. `description` is a short string that |
| 243 | describes the group or an empty string. |
| 244 | Start the description with an upper-case letter. |
| 245 | |
| 246 | `OPT_HIDDEN_GROUP(description)`:: |
| 247 | Like `OPT_GROUP()`, but the group header carries |
| 248 | `PARSE_OPT_HIDDEN`, so it is only shown by `--help-all` and not |
| 249 | by `-h`. Use it to label a group that contains only hidden |
| 250 | options, which would otherwise show an empty header under `-h`. |
| 251 | |
| 252 | `OPT_BOOL(short, long, &int_var, description)`:: |
| 253 | Introduce a boolean option. `int_var` is set to one with |
| 254 | `--option` and set to zero with `--no-option`. |
| 255 | |
| 256 | `OPT_HIDDEN_BOOL(short, long, &int_var, description)`:: |
| 257 | Like `OPT_BOOL()`, but the option carries `PARSE_OPT_HIDDEN`, |
| 258 | so it is hidden from `-h` while still being shown by |
| 259 | `--help-all`. |
| 260 | |
| 261 | `OPT_COUNTUP(short, long, &int_var, description)`:: |
| 262 | Introduce a count-up option. |
| 263 | Each use of `--option` increments `int_var`, starting from zero |
| 264 | (even if initially negative), and `--no-option` resets it to |
| 265 | zero. To determine if `--option` or `--no-option` was encountered at |
| 266 | all, initialize `int_var` to a negative value, and if it is still |
| 267 | negative after parse_options(), then neither `--option` nor |
| 268 | `--no-option` was seen. |
| 269 | |
| 270 | `OPT_BIT(short, long, &int_var, description, mask)`:: |
| 271 | Introduce a boolean option. |
| 272 | If used, `int_var` is bitwise-ored with `mask`. |
| 273 | |
| 274 | `OPT_NEGBIT(short, long, &int_var, description, mask)`:: |
| 275 | Introduce a boolean option. |
| 276 | If used, `int_var` is bitwise-anded with the inverted `mask`. |
| 277 | |
| 278 | `OPT_SET_INT(short, long, &int_var, description, integer)`:: |
| 279 | Introduce an integer option. |
| 280 | `int_var` is set to `integer` with `--option`, and |
| 281 | reset to zero with `--no-option`. |
| 282 | |
| 283 | `OPT_STRING(short, long, &str_var, arg_str, description)`:: |
| 284 | Introduce an option with string argument. |
| 285 | The string argument is put into `str_var`. |
| 286 | |
| 287 | `OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`:: |
| 288 | Introduce an option with string argument. |
| 289 | The string argument is stored as an element in `string_list`. |
| 290 | Use of `--no-option` will clear the list of preceding values. |
| 291 | |
| 292 | `OPT_INTEGER(short, long, &int_var, description)`:: |
| 293 | Introduce an option with integer argument. The argument must be a |
| 294 | integer and may include a suffix of 'k', 'm' or 'g' to |
| 295 | scale the provided value by 1024, 1024^2 or 1024^3 respectively. |
| 296 | The scaled value is put into `int_var`. |
| 297 | |
| 298 | `OPT_UNSIGNED(short, long, &unsigned_long_var, description)`:: |
| 299 | Introduce an option with an unsigned integer argument. The argument must be a |
| 300 | non-negative integer and may include a suffix of 'k', 'm' or 'g' to |
| 301 | scale the provided value by 1024, 1024^2 or 1024^3 respectively. |
| 302 | The scaled value is put into `unsigned_long_var`. |
| 303 | |
| 304 | `OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: |
| 305 | Introduce an option with expiry date argument, see `parse_expiry_date()`. |
| 306 | The timestamp is put into `timestamp_t_var`. |
| 307 | |
| 308 | `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: |
| 309 | Introduce an option with argument. |
| 310 | The argument will be fed into the function given by `func_ptr` |
| 311 | and the result will be put into `var`. |
| 312 | See 'Option Callbacks' below for a more elaborate description. |
| 313 | |
| 314 | `OPT_FILENAME(short, long, &var, description)`:: |
| 315 | Introduce an option with a filename argument. |
| 316 | The filename will be prefixed by passing the filename along with |
| 317 | the prefix argument of `parse_options()` to `prefix_filename()`. |
| 318 | |
| 319 | `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: |
| 320 | Recognize numerical options like -123 and feed the integer as |
| 321 | if it was an argument to the function given by `func_ptr`. |
| 322 | The result will be put into `var`. There can be only one such |
| 323 | option definition. It cannot be negated and it takes no |
| 324 | arguments. Short options that happen to be digits take |
| 325 | precedence over it. |
| 326 | |
| 327 | `OPT_COLOR_FLAG(short, long, &int_var, description)`:: |
| 328 | Introduce an option that takes an optional argument that can |
| 329 | have one of three values: "always", "never", or "auto". If the |
| 330 | argument is not given, it defaults to "always". The `--no-` form |
| 331 | works like `--long=never`; it cannot take an argument. If |
| 332 | "always", set `int_var` to 1; if "never", set `int_var` to 0; if |
| 333 | "auto", set `int_var` to 1 if stdout is a tty or a pager, |
| 334 | 0 otherwise. |
| 335 | |
| 336 | `OPT_NOOP_NOARG(short, long)`:: |
| 337 | Introduce an option that has no effect and takes no arguments. |
| 338 | Use it to hide deprecated options that are still to be recognized |
| 339 | and ignored silently. |
| 340 | |
| 341 | `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: |
| 342 | Introduce an option that will be reconstructed into a char* string, |
| 343 | which must be initialized to NULL. This is useful when you need to |
| 344 | pass the command-line option to another command. Any previous value |
| 345 | will be overwritten, so this should only be used for options where |
| 346 | the last one specified on the command line wins. |
| 347 | |
| 348 | `OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`:: |
| 349 | Introduce an option where all instances of it on the command-line will |
| 350 | be reconstructed into a strvec. This is useful when you need to |
| 351 | pass the command-line option, which can be specified multiple times, |
| 352 | to another command. |
| 353 | |
| 354 | `OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: |
| 355 | Define an "operation mode" option, only one of which in the same |
| 356 | group of "operating mode" options that share the same `int_var` |
| 357 | can be given by the user. `int_var` is set to `enum_val` when the |
| 358 | option is used, but an error is reported if other "operating mode" |
| 359 | option has already set its value to the same `int_var`. |
| 360 | In new commands consider using subcommands instead. |
| 361 | |
| 362 | `OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`:: |
| 363 | Define a subcommand. `subcommand_fn` is put into `fn_ptr` when |
| 364 | this subcommand is used. |
| 365 | |
| 366 | The last element of the array must be `OPT_END()`. |
| 367 | |
| 368 | If not stated otherwise, interpret the arguments as follows: |
| 369 | |
| 370 | * `short` is a character for the short option |
| 371 | (e.g. `'e'` for `-e`, use `0` to omit), |
| 372 | |
| 373 | * `long` is a string for the long option |
| 374 | (e.g. `"example"` for `--example`, use `NULL` to omit), |
| 375 | |
| 376 | * `int_var` is an integer variable, |
| 377 | |
| 378 | * `str_var` is a string variable (`char *`), |
| 379 | |
| 380 | * `arg_str` is the string that is shown as argument |
| 381 | (e.g. `"branch"` will result in `<branch>`). |
| 382 | If set to `NULL`, three dots (`...`) will be displayed. |
| 383 | |
| 384 | * `description` is a short string to describe the effect of the option. |
| 385 | It shall begin with a lower-case letter and a full stop (`.`) shall be |
| 386 | omitted at the end. |
| 387 | |
| 388 | Option Callbacks |
| 389 | ---------------- |
| 390 | |
| 391 | The function must be defined in this form: |
| 392 | |
| 393 | int func(const struct option *opt, const char *arg, int unset) |
| 394 | |
| 395 | The callback mechanism is as follows: |
| 396 | |
| 397 | * Inside `func`, the only interesting member of the structure |
| 398 | given by `opt` is the void pointer `opt->value`. |
| 399 | `*opt->value` will be the value that is saved into `var`, if you |
| 400 | use `OPT_CALLBACK()`. |
| 401 | For example, do `*(unsigned long *)opt->value = 42;` to get 42 |
| 402 | into an `unsigned long` variable. |
| 403 | |
| 404 | * Return value `0` indicates success and non-zero return |
| 405 | value will invoke `usage_with_options()` and, thus, die. |
| 406 | |
| 407 | * If the user negates the option, `arg` is `NULL` and `unset` is 1. |
| 408 | |
| 409 | Sophisticated option parsing |
| 410 | ---------------------------- |
| 411 | |
| 412 | If you need, for example, option callbacks with optional arguments |
| 413 | or without arguments at all, or if you need other special cases, |
| 414 | that are not handled by the macros above, you need to specify the |
| 415 | members of the `option` structure manually. |
| 416 | |
| 417 | This is not covered in this document, but well documented |
| 418 | in `parse-options.h` itself. |
| 419 | |
| 420 | Examples |
| 421 | -------- |
| 422 | |
| 423 | See `test-parse-options.c` and |
| 424 | `builtin/add.c`, |
| 425 | `builtin/clone.c`, |
| 426 | `builtin/commit.c`, |
| 427 | `builtin/fetch.c`, |
| 428 | `builtin/fsck.c`, |
| 429 | `builtin/rm.c` |
| 430 | for real-world examples. |