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* 'stuck' and 'separate form' of options with arguments. 33 `-oArg` is stuck, `-o Arg` is separate form. 34 `--option=Arg` is stuck, `--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`. Conversely, 43 options that begin with `no-` can be 'negated' by removing it. 44 Other long options can be unset (e.g., set string to NULL, set 45 integer to 0) by prepending `no-`. 46 47* Options and non-option arguments can clearly be separated using the `--` 48 option, e.g. `-a -b --option -- --this-is-a-file` indicates that 49 `--this-is-a-file` must not be processed as an option. 50 51Steps to parse options 52---------------------- 53 54. `#include "parse-options.h"` 55 56. define a NULL-terminated 57 `static const char * const builtin_foo_usage[]` array 58 containing alternative usage strings 59 60. define `builtin_foo_options` array as described below 61 in section 'Data Structure'. 62 63. in `cmd_foo(int argc, const char **argv, const char *prefix)` 64 call 65 66 argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); 67+ 68`parse_options()` will filter out the processed options of `argv[]` and leave the 69non-option arguments in `argv[]`. 70`argc` is updated appropriately because of the assignment. 71+ 72You can also pass NULL instead of a usage array as the fifth parameter of 73parse_options(), to avoid displaying a help screen with usage info and 74option list. This should only be done if necessary, e.g. to implement 75a limited parser for only a subset of the options that needs to be run 76before the full parser, which in turn shows the full help message. 77+ 78Flags are the bitwise-or of: 79 80`PARSE_OPT_KEEP_DASHDASH`:: 81 Keep the `--` that usually separates options from 82 non-option arguments. 83 84`PARSE_OPT_STOP_AT_NON_OPTION`:: 85 Usually the whole argument vector is massaged and reordered. 86 Using this flag, processing is stopped at the first non-option 87 argument. 88 89`PARSE_OPT_KEEP_ARGV0`:: 90 Keep the first argument, which contains the program name. It's 91 removed from argv[] by default. 92 93`PARSE_OPT_KEEP_UNKNOWN`:: 94 Keep unknown arguments instead of erroring out. This doesn't 95 work for all combinations of arguments as users might expect 96 it to do. E.g. if the first argument in `--unknown --known` 97 takes a value (which we can't know), the second one is 98 mistakenly interpreted as a known option. Similarly, if 99 `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in 100 `--unknown value` will be mistakenly interpreted as a 101 non-option, not as a value belonging to the unknown option, 102 the parser early. That's why parse_options() errors out if 103 both options are set. 104 105`PARSE_OPT_NO_INTERNAL_HELP`:: 106 By default, parse_options() handles `-h`, `--help` and 107 `--help-all` internally, by showing a help screen. This option 108 turns it off and allows one to add custom handlers for these 109 options, or to just leave them unknown. 110 111Data Structure 112-------------- 113 114The main data structure is an array of the `option` struct, 115say `static struct option builtin_add_options[]`. 116There are some macros to easily define options: 117 118`OPT__ABBREV(&int_var)`:: 119 Add `--abbrev[=<n>]`. 120 121`OPT__COLOR(&int_var, description)`:: 122 Add `--color[=<when>]` and `--no-color`. 123 124`OPT__DRY_RUN(&int_var, description)`:: 125 Add `-n, --dry-run`. 126 127`OPT__FORCE(&int_var, description)`:: 128 Add `-f, --force`. 129 130`OPT__QUIET(&int_var, description)`:: 131 Add `-q, --quiet`. 132 133`OPT__VERBOSE(&int_var, description)`:: 134 Add `-v, --verbose`. 135 136`OPT_GROUP(description)`:: 137 Start an option group. `description` is a short string that 138 describes the group or an empty string. 139 Start the description with an upper-case letter. 140 141`OPT_BOOL(short, long, &int_var, description)`:: 142 Introduce a boolean option. `int_var` is set to one with 143 `--option` and set to zero with `--no-option`. 144 145`OPT_COUNTUP(short, long, &int_var, description)`:: 146 Introduce a count-up option. 147 Each use of `--option` increments `int_var`, starting from zero 148 (even if initially negative), and `--no-option` resets it to 149 zero. To determine if `--option` or `--no-option` was encountered at 150 all, initialize `int_var` to a negative value, and if it is still 151 negative after parse_options(), then neither `--option` nor 152 `--no-option` was seen. 153 154`OPT_BIT(short, long, &int_var, description, mask)`:: 155 Introduce a boolean option. 156 If used, `int_var` is bitwise-ored with `mask`. 157 158`OPT_NEGBIT(short, long, &int_var, description, mask)`:: 159 Introduce a boolean option. 160 If used, `int_var` is bitwise-anded with the inverted `mask`. 161 162`OPT_SET_INT(short, long, &int_var, description, integer)`:: 163 Introduce an integer option. 164 `int_var` is set to `integer` with `--option`, and 165 reset to zero with `--no-option`. 166 167`OPT_STRING(short, long, &str_var, arg_str, description)`:: 168 Introduce an option with string argument. 169 The string argument is put into `str_var`. 170 171`OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`:: 172 Introduce an option with string argument. 173 The string argument is stored as an element in `string_list`. 174 Use of `--no-option` will clear the list of preceding values. 175 176`OPT_INTEGER(short, long, &int_var, description)`:: 177 Introduce an option with integer argument. 178 The integer is put into `int_var`. 179 180`OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: 181 Introduce an option with a size argument. The argument must be a 182 non-negative integer and may include a suffix of 'k', 'm' or 'g' to 183 scale the provided value by 1024, 1024^2 or 1024^3 respectively. 184 The scaled value is put into `unsigned_long_var`. 185 186`OPT_DATE(short, long, ×tamp_t_var, description)`:: 187 Introduce an option with date argument, see `approxidate()`. 188 The timestamp is put into `timestamp_t_var`. 189 190`OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: 191 Introduce an option with expiry date argument, see `parse_expiry_date()`. 192 The timestamp is put into `timestamp_t_var`. 193 194`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: 195 Introduce an option with argument. 196 The argument will be fed into the function given by `func_ptr` 197 and the result will be put into `var`. 198 See 'Option Callbacks' below for a more elaborate description. 199 200`OPT_FILENAME(short, long, &var, description)`:: 201 Introduce an option with a filename argument. 202 The filename will be prefixed by passing the filename along with 203 the prefix argument of `parse_options()` to `prefix_filename()`. 204 205`OPT_ARGUMENT(long, description)`:: 206 Introduce a long-option argument that will be kept in `argv[]`. 207 208`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: 209 Recognize numerical options like -123 and feed the integer as 210 if it was an argument to the function given by `func_ptr`. 211 The result will be put into `var`. There can be only one such 212 option definition. It cannot be negated and it takes no 213 arguments. Short options that happen to be digits take 214 precedence over it. 215 216`OPT_COLOR_FLAG(short, long, &int_var, description)`:: 217 Introduce an option that takes an optional argument that can 218 have one of three values: "always", "never", or "auto". If the 219 argument is not given, it defaults to "always". The `--no-` form 220 works like `--long=never`; it cannot take an argument. If 221 "always", set `int_var` to 1; if "never", set `int_var` to 0; if 222 "auto", set `int_var` to 1 if stdout is a tty or a pager, 223 0 otherwise. 224 225`OPT_NOOP_NOARG(short, long)`:: 226 Introduce an option that has no effect and takes no arguments. 227 Use it to hide deprecated options that are still to be recognized 228 and ignored silently. 229 230`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: 231 Introduce an option that will be reconstructed into a char* string, 232 which must be initialized to NULL. This is useful when you need to 233 pass the command-line option to another command. Any previous value 234 will be overwritten, so this should only be used for options where 235 the last one specified on the command line wins. 236 237`OPT_PASSTHRU_ARGV(short, long, &argv_array_var, arg_str, description, flags)`:: 238 Introduce an option where all instances of it on the command-line will 239 be reconstructed into an argv_array. This is useful when you need to 240 pass the command-line option, which can be specified multiple times, 241 to another command. 242 243`OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: 244 Define an "operation mode" option, only one of which in the same 245 group of "operating mode" options that share the same `int_var` 246 can be given by the user. `enum_val` is set to `int_var` when the 247 option is used, but an error is reported if other "operating mode" 248 option has already set its value to the same `int_var`. 249 250 251The last element of the array must be `OPT_END()`. 252 253If not stated otherwise, interpret the arguments as follows: 254 255* `short` is a character for the short option 256 (e.g. `'e'` for `-e`, use `0` to omit), 257 258* `long` is a string for the long option 259 (e.g. `"example"` for `--example`, use `NULL` to omit), 260 261* `int_var` is an integer variable, 262 263* `str_var` is a string variable (`char *`), 264 265* `arg_str` is the string that is shown as argument 266 (e.g. `"branch"` will result in `<branch>`). 267 If set to `NULL`, three dots (`...`) will be displayed. 268 269* `description` is a short string to describe the effect of the option. 270 It shall begin with a lower-case letter and a full stop (`.`) shall be 271 omitted at the end. 272 273Option Callbacks 274---------------- 275 276The function must be defined in this form: 277 278 int func(const struct option *opt, const char *arg, int unset) 279 280The callback mechanism is as follows: 281 282* Inside `func`, the only interesting member of the structure 283 given by `opt` is the void pointer `opt->value`. 284 `*opt->value` will be the value that is saved into `var`, if you 285 use `OPT_CALLBACK()`. 286 For example, do `*(unsigned long *)opt->value = 42;` to get 42 287 into an `unsigned long` variable. 288 289* Return value `0` indicates success and non-zero return 290 value will invoke `usage_with_options()` and, thus, die. 291 292* If the user negates the option, `arg` is `NULL` and `unset` is 1. 293 294Sophisticated option parsing 295---------------------------- 296 297If you need, for example, option callbacks with optional arguments 298or without arguments at all, or if you need other special cases, 299that are not handled by the macros above, you need to specify the 300members of the `option` structure manually. 301 302This is not covered in this document, but well documented 303in `parse-options.h` itself. 304 305Examples 306-------- 307 308See `test-parse-options.c` and 309`builtin/add.c`, 310`builtin/clone.c`, 311`builtin/commit.c`, 312`builtin/fetch.c`, 313`builtin/fsck.c`, 314`builtin/rm.c` 315for real-world examples.