technical/api-parse-options.txt

   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 There are some macros to easily define options:
 154
 155 `OPT__ABBREV(&int_var)`::
 156         Add `--abbrev[=<n>]`.
 157
 158 `OPT__COLOR(&int_var, description)`::
 159         Add `--color[=<when>]` and `--no-color`.
 160
 161 `OPT__DRY_RUN(&int_var, description)`::
 162         Add `-n, --dry-run`.
 163
 164 `OPT__FORCE(&int_var, description)`::
 165         Add `-f, --force`.
 166
 167 `OPT__QUIET(&int_var, description)`::
 168         Add `-q, --quiet`.
 169
 170 `OPT__VERBOSE(&int_var, description)`::
 171         Add `-v, --verbose`.
 172
 173 `OPT_GROUP(description)`::
 174         Start an option group. `description` is a short string that
 175         describes the group or an empty string.
 176         Start the description with an upper-case letter.
 177
 178 `OPT_BOOL(short, long, &int_var, description)`::
 179         Introduce a boolean option. `int_var` is set to one with
 180         `--option` and set to zero with `--no-option`.
 181
 182 `OPT_COUNTUP(short, long, &int_var, description)`::
 183         Introduce a count-up option.
 184         Each use of `--option` increments `int_var`, starting from zero
 185         (even if initially negative), and `--no-option` resets it to
 186         zero. To determine if `--option` or `--no-option` was encountered at
 187         all, initialize `int_var` to a negative value, and if it is still
 188         negative after parse_options(), then neither `--option` nor
 189         `--no-option` was seen.
 190
 191 `OPT_BIT(short, long, &int_var, description, mask)`::
 192         Introduce a boolean option.
 193         If used, `int_var` is bitwise-ored with `mask`.
 194
 195 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
 196         Introduce a boolean option.
 197         If used, `int_var` is bitwise-anded with the inverted `mask`.
 198
 199 `OPT_SET_INT(short, long, &int_var, description, integer)`::
 200         Introduce an integer option.
 201         `int_var` is set to `integer` with `--option`, and
 202         reset to zero with `--no-option`.
 203
 204 `OPT_STRING(short, long, &str_var, arg_str, description)`::
 205         Introduce an option with string argument.
 206         The string argument is put into `str_var`.
 207
 208 `OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`::
 209         Introduce an option with string argument.
 210         The string argument is stored as an element in `string_list`.
 211         Use of `--no-option` will clear the list of preceding values.
 212
 213 `OPT_INTEGER(short, long, &int_var, description)`::
 214         Introduce an option with integer argument.
 215         The integer is put into `int_var`.
 216
 217 `OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`::
 218         Introduce an option with a size argument. The argument must be a
 219         non-negative integer and may include a suffix of 'k', 'm' or 'g' to
 220         scale the provided value by 1024, 1024^2 or 1024^3 respectively.
 221         The scaled value is put into `unsigned_long_var`.
 222
 223 `OPT_EXPIRY_DATE(short, long, &timestamp_t_var, description)`::
 224         Introduce an option with expiry date argument, see `parse_expiry_date()`.
 225         The timestamp is put into `timestamp_t_var`.
 226
 227 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
 228         Introduce an option with argument.
 229         The argument will be fed into the function given by `func_ptr`
 230         and the result will be put into `var`.
 231         See 'Option Callbacks' below for a more elaborate description.
 232
 233 `OPT_FILENAME(short, long, &var, description)`::
 234         Introduce an option with a filename argument.
 235         The filename will be prefixed by passing the filename along with
 236         the prefix argument of `parse_options()` to `prefix_filename()`.
 237
 238 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
 239         Recognize numerical options like -123 and feed the integer as
 240         if it was an argument to the function given by `func_ptr`.
 241         The result will be put into `var`.  There can be only one such
 242         option definition.  It cannot be negated and it takes no
 243         arguments.  Short options that happen to be digits take
 244         precedence over it.
 245
 246 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
 247         Introduce an option that takes an optional argument that can
 248         have one of three values: "always", "never", or "auto".  If the
 249         argument is not given, it defaults to "always".  The `--no-` form
 250         works like `--long=never`; it cannot take an argument.  If
 251         "always", set `int_var` to 1; if "never", set `int_var` to 0; if
 252         "auto", set `int_var` to 1 if stdout is a tty or a pager,
 253         0 otherwise.
 254
 255 `OPT_NOOP_NOARG(short, long)`::
 256         Introduce an option that has no effect and takes no arguments.
 257         Use it to hide deprecated options that are still to be recognized
 258         and ignored silently.
 259
 260 `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
 261         Introduce an option that will be reconstructed into a char* string,
 262         which must be initialized to NULL. This is useful when you need to
 263         pass the command-line option to another command. Any previous value
 264         will be overwritten, so this should only be used for options where
 265         the last one specified on the command line wins.
 266
 267 `OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`::
 268         Introduce an option where all instances of it on the command-line will
 269         be reconstructed into a strvec. This is useful when you need to
 270         pass the command-line option, which can be specified multiple times,
 271         to another command.
 272
 273 `OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
 274         Define an "operation mode" option, only one of which in the same
 275         group of "operating mode" options that share the same `int_var`
 276         can be given by the user. `int_var` is set to `enum_val` when the
 277         option is used, but an error is reported if other "operating mode"
 278         option has already set its value to the same `int_var`.
 279         In new commands consider using subcommands instead.
 280
 281 `OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::
 282         Define a subcommand.  `subcommand_fn` is put into `fn_ptr` when
 283         this subcommand is used.
 284
 285 The last element of the array must be `OPT_END()`.
 286
 287 If not stated otherwise, interpret the arguments as follows:
 288
 289 * `short` is a character for the short option
 290   (e.g. `'e'` for `-e`, use `0` to omit),
 291
 292 * `long` is a string for the long option
 293   (e.g. `"example"` for `--example`, use `NULL` to omit),
 294
 295 * `int_var` is an integer variable,
 296
 297 * `str_var` is a string variable (`char *`),
 298
 299 * `arg_str` is the string that is shown as argument
 300   (e.g. `"branch"` will result in `<branch>`).
 301   If set to `NULL`, three dots (`...`) will be displayed.
 302
 303 * `description` is a short string to describe the effect of the option.
 304   It shall begin with a lower-case letter and a full stop (`.`) shall be
 305   omitted at the end.
 306
 307 Option Callbacks
 308 ----------------
 309
 310 The function must be defined in this form:
 311
 312         int func(const struct option *opt, const char *arg, int unset)
 313
 314 The callback mechanism is as follows:
 315
 316 * Inside `func`, the only interesting member of the structure
 317   given by `opt` is the void pointer `opt->value`.
 318   `*opt->value` will be the value that is saved into `var`, if you
 319   use `OPT_CALLBACK()`.
 320   For example, do `*(unsigned long *)opt->value = 42;` to get 42
 321   into an `unsigned long` variable.
 322
 323 * Return value `0` indicates success and non-zero return
 324   value will invoke `usage_with_options()` and, thus, die.
 325
 326 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
 327
 328 Sophisticated option parsing
 329 ----------------------------
 330
 331 If you need, for example, option callbacks with optional arguments
 332 or without arguments at all, or if you need other special cases,
 333 that are not handled by the macros above, you need to specify the
 334 members of the `option` structure manually.
 335
 336 This is not covered in this document, but well documented
 337 in `parse-options.h` itself.
 338
 339 Examples
 340 --------
 341
 342 See `test-parse-options.c` and
 343 `builtin/add.c`,
 344 `builtin/clone.c`,
 345 `builtin/commit.c`,
 346 `builtin/fetch.c`,
 347 `builtin/fsck.c`,
 348 `builtin/rm.c`
 349 for real-world examples.