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, 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 fourth 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         stopping the parser early.
 100
 101 `PARSE_OPT_NO_INTERNAL_HELP`::
 102         By default, parse_options() handles `-h`, `--help` and
 103         `--help-all` internally, by showing a help screen.  This option
 104         turns it off and allows one to add custom handlers for these
 105         options, or to just leave them unknown.
 106
 107 Data Structure
 108 --------------
 109
 110 The main data structure is an array of the `option` struct,
 111 say `static struct option builtin_add_options[]`.
 112 There are some macros to easily define options:
 113
 114 `OPT__ABBREV(&int_var)`::
 115         Add `\--abbrev[=<n>]`.
 116
 117 `OPT__DRY_RUN(&int_var)`::
 118         Add `-n, \--dry-run`.
 119
 120 `OPT__QUIET(&int_var)`::
 121         Add `-q, \--quiet`.
 122
 123 `OPT__VERBOSE(&int_var)`::
 124         Add `-v, \--verbose`.
 125
 126 `OPT_GROUP(description)`::
 127         Start an option group. `description` is a short string that
 128         describes the group or an empty string.
 129         Start the description with an upper-case letter.
 130
 131 `OPT_BOOLEAN(short, long, &int_var, description)`::
 132         Introduce a boolean option.
 133         `int_var` is incremented on each use.
 134
 135 `OPT_BIT(short, long, &int_var, description, mask)`::
 136         Introduce a boolean option.
 137         If used, `int_var` is bitwise-ored with `mask`.
 138
 139 `OPT_SET_INT(short, long, &int_var, description, integer)`::
 140         Introduce a boolean option.
 141         If used, set `int_var` to `integer`.
 142
 143 `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
 144         Introduce a boolean option.
 145         If used, set `ptr_var` to `ptr`.
 146
 147 `OPT_STRING(short, long, &str_var, arg_str, description)`::
 148         Introduce an option with string argument.
 149         The string argument is put into `str_var`.
 150
 151 `OPT_INTEGER(short, long, &int_var, description)`::
 152         Introduce an option with integer argument.
 153         The integer is put into `int_var`.
 154
 155 `OPT_DATE(short, long, &int_var, description)`::
 156         Introduce an option with date argument, see `approxidate()`.
 157         The timestamp is put into `int_var`.
 158
 159 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
 160         Introduce an option with argument.
 161         The argument will be fed into the function given by `func_ptr`
 162         and the result will be put into `var`.
 163         See 'Option Callbacks' below for a more elaborate description.
 164
 165 `OPT_ARGUMENT(long, description)`::
 166         Introduce a long-option argument that will be kept in `argv[]`.
 167
 168
 169 The last element of the array must be `OPT_END()`.
 170
 171 If not stated otherwise, interpret the arguments as follows:
 172
 173 * `short` is a character for the short option
 174   (e.g. `\'e\'` for `-e`, use `0` to omit),
 175
 176 * `long` is a string for the long option
 177   (e.g. `"example"` for `\--example`, use `NULL` to omit),
 178
 179 * `int_var` is an integer variable,
 180
 181 * `str_var` is a string variable (`char *`),
 182
 183 * `arg_str` is the string that is shown as argument
 184   (e.g. `"branch"` will result in `<branch>`).
 185   If set to `NULL`, three dots (`...`) will be displayed.
 186
 187 * `description` is a short string to describe the effect of the option.
 188   It shall begin with a lower-case letter and a full stop (`.`) shall be
 189   omitted at the end.
 190
 191 Option Callbacks
 192 ----------------
 193
 194 The function must be defined in this form:
 195
 196         int func(const struct option *opt, const char *arg, int unset)
 197
 198 The callback mechanism is as follows:
 199
 200 * Inside `funct`, the only interesting member of the structure
 201   given by `opt` is the void pointer `opt->value`.
 202   `\*opt->value` will be the value that is saved into `var`, if you
 203   use `OPT_CALLBACK()`.
 204   For example, do `*(unsigned long *)opt->value = 42;` to get 42
 205   into an `unsigned long` variable.
 206
 207 * Return value `0` indicates success and non-zero return
 208   value will invoke `usage_with_options()` and, thus, die.
 209
 210 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
 211
 212 Sophisticated option parsing
 213 ----------------------------
 214
 215 If you need, for example, option callbacks with optional arguments
 216 or without arguments at all, or if you need other special cases,
 217 that are not handled by the macros above, you need to specify the
 218 members of the `option` structure manually.
 219
 220 This is not covered in this document, but well documented
 221 in `parse-options.h` itself.
 222
 223 Examples
 224 --------
 225
 226 See `test-parse-options.c` and
 227 `builtin-add.c`,
 228 `builtin-clone.c`,
 229 `builtin-commit.c`,
 230 `builtin-fetch.c`,
 231 `builtin-fsck.c`,
 232 `builtin-rm.c`
 233 for real-world examples.