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 Flags are the bitwise-or of:
  70
  71 `PARSE_OPT_KEEP_DASHDASH`::
  72         Keep the `\--` that usually separates options from
  73         non-option arguments.
  74
  75 `PARSE_OPT_STOP_AT_NON_OPTION`::
  76         Usually the whole argument vector is massaged and reordered.
  77         Using this flag, processing is stopped at the first non-option
  78         argument.
  79
  80 Data Structure
  81 --------------
  82
  83 The main data structure is an array of the `option` struct,
  84 say `static struct option builtin_add_options[]`.
  85 There are some macros to easily define options:
  86
  87 `OPT__ABBREV(&int_var)`::
  88         Add `\--abbrev[=<n>]`.
  89
  90 `OPT__DRY_RUN(&int_var)`::
  91         Add `-n, \--dry-run`.
  92
  93 `OPT__QUIET(&int_var)`::
  94         Add `-q, \--quiet`.
  95
  96 `OPT__VERBOSE(&int_var)`::
  97         Add `-v, \--verbose`.
  98
  99 `OPT_GROUP(description)`::
 100         Start an option group. `description` is a short string that
 101         describes the group or an empty string.
 102         Start the description with an upper-case letter.
 103
 104 `OPT_BOOLEAN(short, long, &int_var, description)`::
 105         Introduce a boolean option.
 106         `int_var` is incremented on each use.
 107
 108 `OPT_BIT(short, long, &int_var, description, mask)`::
 109         Introduce a boolean option.
 110         If used, `int_var` is bitwise-ored with `mask`.
 111
 112 `OPT_SET_INT(short, long, &int_var, description, integer)`::
 113         Introduce a boolean option.
 114         If used, set `int_var` to `integer`.
 115
 116 `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
 117         Introduce a boolean option.
 118         If used, set `ptr_var` to `ptr`.
 119
 120 `OPT_STRING(short, long, &str_var, arg_str, description)`::
 121         Introduce an option with string argument.
 122         The string argument is put into `str_var`.
 123
 124 `OPT_INTEGER(short, long, &int_var, description)`::
 125         Introduce an option with integer argument.
 126         The integer is put into `int_var`.
 127
 128 `OPT_DATE(short, long, &int_var, description)`::
 129         Introduce an option with date argument, see `approxidate()`.
 130         The timestamp is put into `int_var`.
 131
 132 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
 133         Introduce an option with argument.
 134         The argument will be fed into the function given by `func_ptr`
 135         and the result will be put into `var`.
 136         See 'Option Callbacks' below for a more elaborate description.
 137
 138 `OPT_ARGUMENT(long, description)`::
 139         Introduce a long-option argument that will be kept in `argv[]`.
 140
 141
 142 The last element of the array must be `OPT_END()`.
 143
 144 If not stated otherwise, interpret the arguments as follows:
 145
 146 * `short` is a character for the short option
 147   (e.g. `\'e\'` for `-e`, use `0` to omit),
 148
 149 * `long` is a string for the long option
 150   (e.g. `"example"` for `\--example`, use `NULL` to omit),
 151
 152 * `int_var` is an integer variable,
 153
 154 * `str_var` is a string variable (`char *`),
 155
 156 * `arg_str` is the string that is shown as argument
 157   (e.g. `"branch"` will result in `<branch>`).
 158   If set to `NULL`, three dots (`...`) will be displayed.
 159
 160 * `description` is a short string to describe the effect of the option.
 161   It shall begin with a lower-case letter and a full stop (`.`) shall be
 162   omitted at the end.
 163
 164 Option Callbacks
 165 ----------------
 166
 167 The function must be defined in this form:
 168
 169         int func(const struct option *opt, const char *arg, int unset)
 170
 171 The callback mechanism is as follows:
 172
 173 * Inside `funct`, the only interesting member of the structure
 174   given by `opt` is the void pointer `opt->value`.
 175   `\*opt->value` will be the value that is saved into `var`, if you
 176   use `OPT_CALLBACK()`.
 177   For example, do `*(unsigned long *)opt->value = 42;` to get 42
 178   into an `unsigned long` variable.
 179
 180 * Return value `0` indicates success and non-zero return
 181   value will invoke `usage_with_options()` and, thus, die.
 182
 183 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
 184
 185 Sophisticated option parsing
 186 ----------------------------
 187
 188 If you need, for example, option callbacks with optional arguments
 189 or without arguments at all, or if you need other special cases,
 190 that are not handled by the macros above, you need to specify the
 191 members of the `option` structure manually.
 192
 193 This is not covered in this document, but well documented
 194 in `parse-options.h` itself.
 195
 196 Examples
 197 --------
 198
 199 See `test-parse-options.c` and
 200 `builtin-add.c`,
 201 `builtin-clone.c`,
 202 `builtin-commit.c`,
 203 `builtin-fetch.c`,
 204 `builtin-fsck.c`,
 205 `builtin-rm.c`
 206 for real-world examples.