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