1parse-options API 2================= 3 4The parse-options API is used to parse and massage options in git 5and to provide a usage help with consistent look. 6 7Basics 8------ 9 10The argument vector `argv[]` may usually contain mandatory or optional 11'non-option arguments', e.g. a filename or a branch, and 'options'. 12Options are optional arguments that start with a dash and 13that 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 30The 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 48Steps 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 66non-option arguments in `argv[]`. 67`argc` is updated appropriately because of the assignment. 68+ 69Flags 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 80Data Structure 81-------------- 82 83The main data structure is an array of the `option` struct, 84say `static struct option builtin_add_options[]`. 85There 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 142The last element of the array must be `OPT_END()`. 143 144If 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 164Option Callbacks 165---------------- 166 167The function must be defined in this form: 168 169 int func(const struct option *opt, const char *arg, int unset) 170 171The 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 185Sophisticated option parsing 186---------------------------- 187 188If you need, for example, option callbacks with optional arguments 189or without arguments at all, or if you need other special cases, 190that are not handled by the macros above, you need to specify the 191members of the `option` structure manually. 192 193This is not covered in this document, but well documented 194in `parse-options.h` itself. 195 196Examples 197-------- 198 199See `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` 206for real-world examples.