Documentation/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, and 'options'.
  12 Options are optional arguments that start with a dash and
  13 that allow to change the behavior of a command.
  14
  15 * There are basically three types of options:
  16   'boolean' options,
  17   options with (mandatory) 'arguments' and
  18   options with 'optional arguments'
  19   (i.e. a boolean option that can be adjusted).
  20
  21 * There are basically two forms of options:
  22   'Short options' consist of one dash (`-`) and one alphanumeric
  23   character.
  24   'Long options' begin with two dashes (`\--`) and some
  25   alphanumeric characters.
  26
  27 * Options are case-sensitive.
  28   Please define 'lower-case long options' only.
  29
  30 The parse-options API allows:
  31
  32 * 'sticked' and 'separate form' of options with arguments.
  33   `-oArg` is sticked, `-o Arg` is separate form.
  34   `\--option=Arg` is sticked, `\--option Arg` is separate form.
  35
  36 * Long options may be 'abbreviated', as long as the abbreviation
  37   is unambiguous.
  38
  39 * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
  40
  41 * Boolean long options can be 'negated' (or 'unset') by prepending
  42   `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. Conversely,
  43   options that begin with `no-` can be 'negated' by removing it.
  44
  45 * Options and non-option arguments can clearly be separated using the `\--`
  46   option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that
  47   `\--this-is-a-file` must not be processed as an option.
  48
  49 Steps to parse options
  50 ----------------------
  51
  52 . `#include "parse-options.h"`
  53
  54 . define a NULL-terminated
  55   `static const char * const builtin_foo_usage[]` array
  56   containing alternative usage strings
  57
  58 . define `builtin_foo_options` array as described below
  59   in section 'Data Structure'.
  60
  61 . in `cmd_foo(int argc, const char **argv, const char *prefix)`
  62   call
  63
  64         argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
  65 +
  66 `parse_options()` will filter out the processed options of `argv[]` and leave the
  67 non-option arguments in `argv[]`.
  68 `argc` is updated appropriately because of the assignment.
  69 +
  70 You can also pass NULL instead of a usage array as the fifth parameter of
  71 parse_options(), to avoid displaying a help screen with usage info and
  72 option list.  This should only be done if necessary, e.g. to implement
  73 a limited parser for only a subset of the options that needs to be run
  74 before the full parser, which in turn shows the full help message.
  75 +
  76 Flags are the bitwise-or of:
  77
  78 `PARSE_OPT_KEEP_DASHDASH`::
  79         Keep the `\--` that usually separates options from
  80         non-option arguments.
  81
  82 `PARSE_OPT_STOP_AT_NON_OPTION`::
  83         Usually the whole argument vector is massaged and reordered.
  84         Using this flag, processing is stopped at the first non-option
  85         argument.
  86
  87 `PARSE_OPT_KEEP_ARGV0`::
  88         Keep the first argument, which contains the program name.  It's
  89         removed from argv[] by default.
  90
  91 `PARSE_OPT_KEEP_UNKNOWN`::
  92         Keep unknown arguments instead of erroring out.  This doesn't
  93         work for all combinations of arguments as users might expect
  94         it to do.  E.g. if the first argument in `--unknown --known`
  95         takes a value (which we can't know), the second one is
  96         mistakenly interpreted as a known option.  Similarly, if
  97         `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in
  98         `--unknown value` will be mistakenly interpreted as a
  99         non-option, not as a value belonging to the unknown option,
 100         the parser early.  That's why parse_options() errors out if
 101         both options are set.
 102
 103 `PARSE_OPT_NO_INTERNAL_HELP`::
 104         By default, parse_options() handles `-h`, `--help` and
 105         `--help-all` internally, by showing a help screen.  This option
 106         turns it off and allows one to add custom handlers for these
 107         options, or to just leave them unknown.
 108
 109 Data Structure
 110 --------------
 111
 112 The main data structure is an array of the `option` struct,
 113 say `static struct option builtin_add_options[]`.
 114 There are some macros to easily define options:
 115
 116 `OPT__ABBREV(&int_var)`::
 117         Add `\--abbrev[=<n>]`.
 118
 119 `OPT__COLOR(&int_var, description)`::
 120         Add `\--color[=<when>]` and `--no-color`.
 121
 122 `OPT__DRY_RUN(&int_var, description)`::
 123         Add `-n, \--dry-run`.
 124
 125 `OPT__FORCE(&int_var, description)`::
 126         Add `-f, \--force`.
 127
 128 `OPT__QUIET(&int_var, description)`::
 129         Add `-q, \--quiet`.
 130
 131 `OPT__VERBOSE(&int_var, description)`::
 132         Add `-v, \--verbose`.
 133
 134 `OPT_GROUP(description)`::
 135         Start an option group. `description` is a short string that
 136         describes the group or an empty string.
 137         Start the description with an upper-case letter.
 138
 139 `OPT_BOOL(short, long, &int_var, description)`::
 140         Introduce a boolean option. `int_var` is set to one with
 141         `--option` and set to zero with `--no-option`.
 142
 143 `OPT_COUNTUP(short, long, &int_var, description)`::
 144         Introduce a count-up option.
 145         `int_var` is incremented on each use of `--option`, and
 146         reset to zero with `--no-option`.
 147
 148 `OPT_BIT(short, long, &int_var, description, mask)`::
 149         Introduce a boolean option.
 150         If used, `int_var` is bitwise-ored with `mask`.
 151
 152 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
 153         Introduce a boolean option.
 154         If used, `int_var` is bitwise-anded with the inverted `mask`.
 155
 156 `OPT_SET_INT(short, long, &int_var, description, integer)`::
 157         Introduce an integer option.
 158         `int_var` is set to `integer` with `--option`, and
 159         reset to zero with `--no-option`.
 160
 161 `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
 162         Introduce a boolean option.
 163         If used, set `ptr_var` to `ptr`.
 164
 165 `OPT_STRING(short, long, &str_var, arg_str, description)`::
 166         Introduce an option with string argument.
 167         The string argument is put into `str_var`.
 168
 169 `OPT_INTEGER(short, long, &int_var, description)`::
 170         Introduce an option with integer argument.
 171         The integer is put into `int_var`.
 172
 173 `OPT_DATE(short, long, &int_var, description)`::
 174         Introduce an option with date argument, see `approxidate()`.
 175         The timestamp is put into `int_var`.
 176
 177 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
 178         Introduce an option with argument.
 179         The argument will be fed into the function given by `func_ptr`
 180         and the result will be put into `var`.
 181         See 'Option Callbacks' below for a more elaborate description.
 182
 183 `OPT_FILENAME(short, long, &var, description)`::
 184         Introduce an option with a filename argument.
 185         The filename will be prefixed by passing the filename along with
 186         the prefix argument of `parse_options()` to `prefix_filename()`.
 187
 188 `OPT_ARGUMENT(long, description)`::
 189         Introduce a long-option argument that will be kept in `argv[]`.
 190
 191 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
 192         Recognize numerical options like -123 and feed the integer as
 193         if it was an argument to the function given by `func_ptr`.
 194         The result will be put into `var`.  There can be only one such
 195         option definition.  It cannot be negated and it takes no
 196         arguments.  Short options that happen to be digits take
 197         precedence over it.
 198
 199 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
 200         Introduce an option that takes an optional argument that can
 201         have one of three values: "always", "never", or "auto".  If the
 202         argument is not given, it defaults to "always".  The `--no-` form
 203         works like `--long=never`; it cannot take an argument.  If
 204         "always", set `int_var` to 1; if "never", set `int_var` to 0; if
 205         "auto", set `int_var` to 1 if stdout is a tty or a pager,
 206         0 otherwise.
 207
 208 `OPT_NOOP_NOARG(short, long)`::
 209         Introduce an option that has no effect and takes no arguments.
 210         Use it to hide deprecated options that are still to be recognized
 211         and ignored silently.
 212
 213
 214 The last element of the array must be `OPT_END()`.
 215
 216 If not stated otherwise, interpret the arguments as follows:
 217
 218 * `short` is a character for the short option
 219   (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
 220
 221 * `long` is a string for the long option
 222   (e.g. `"example"` for `\--example`, use `NULL` to omit),
 223
 224 * `int_var` is an integer variable,
 225
 226 * `str_var` is a string variable (`char *`),
 227
 228 * `arg_str` is the string that is shown as argument
 229   (e.g. `"branch"` will result in `<branch>`).
 230   If set to `NULL`, three dots (`...`) will be displayed.
 231
 232 * `description` is a short string to describe the effect of the option.
 233   It shall begin with a lower-case letter and a full stop (`.`) shall be
 234   omitted at the end.
 235
 236 Option Callbacks
 237 ----------------
 238
 239 The function must be defined in this form:
 240
 241         int func(const struct option *opt, const char *arg, int unset)
 242
 243 The callback mechanism is as follows:
 244
 245 * Inside `func`, the only interesting member of the structure
 246   given by `opt` is the void pointer `opt\->value`.
 247   `\*opt\->value` will be the value that is saved into `var`, if you
 248   use `OPT_CALLBACK()`.
 249   For example, do `*(unsigned long *)opt\->value = 42;` to get 42
 250   into an `unsigned long` variable.
 251
 252 * Return value `0` indicates success and non-zero return
 253   value will invoke `usage_with_options()` and, thus, die.
 254
 255 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
 256
 257 Sophisticated option parsing
 258 ----------------------------
 259
 260 If you need, for example, option callbacks with optional arguments
 261 or without arguments at all, or if you need other special cases,
 262 that are not handled by the macros above, you need to specify the
 263 members of the `option` structure manually.
 264
 265 This is not covered in this document, but well documented
 266 in `parse-options.h` itself.
 267
 268 Examples
 269 --------
 270
 271 See `test-parse-options.c` and
 272 `builtin-add.c`,
 273 `builtin-clone.c`,
 274 `builtin-commit.c`,
 275 `builtin-fetch.c`,
 276 `builtin-fsck.c`,
 277 `builtin-rm.c`
 278 for real-world examples.