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, prefix, 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 the fifth 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 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 108Data Structure 109-------------- 110 111The main data structure is an array of the `option` struct, 112say `static struct option builtin_add_options[]`. 113There 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 213The last element of the array must be `OPT_END()`. 214 215If 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 235Option Callbacks 236---------------- 237 238The function must be defined in this form: 239 240 int func(const struct option *opt, const char *arg, int unset) 241 242The 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 256Sophisticated option parsing 257---------------------------- 258 259If you need, for example, option callbacks with optional arguments 260or without arguments at all, or if you need other special cases, 261that are not handled by the macros above, you need to specify the 262members of the `option` structure manually. 263 264This is not covered in this document, but well documented 265in `parse-options.h` itself. 266 267Examples 268-------- 269 270See `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` 277for real-world examples.