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+ 69You can also pass NULL instead of a usage array as fourth parameter of 70parse_options(), to avoid displaying a help screen with usage info and 71option list. This should only be done if necessary, e.g. to implement 72a limited parser for only a subset of the options that needs to be run 73before the full parser, which in turn shows the full help message. 74+ 75Flags 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 107Data Structure 108-------------- 109 110The main data structure is an array of the `option` struct, 111say `static struct option builtin_add_options[]`. 112There 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 169The last element of the array must be `OPT_END()`. 170 171If 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 191Option Callbacks 192---------------- 193 194The function must be defined in this form: 195 196 int func(const struct option *opt, const char *arg, int unset) 197 198The 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 212Sophisticated option parsing 213---------------------------- 214 215If you need, for example, option callbacks with optional arguments 216or without arguments at all, or if you need other special cases, 217that are not handled by the macros above, you need to specify the 218members of the `option` structure manually. 219 220This is not covered in this document, but well documented 221in `parse-options.h` itself. 222 223Examples 224-------- 225 226See `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` 233for real-world examples.