]>
Commit | Line | Data |
---|---|---|
530e741c JH |
1 | parse-options API |
2 | ================= | |
3 | ||
2de9b711 | 4 | The parse-options API is used to parse and massage options in Git |
224712e5 | 5 | and to provide a usage help with consistent look. |
530e741c | 6 | |
224712e5 SB |
7 | Basics |
8 | ------ | |
9 | ||
10 | The argument vector `argv[]` may usually contain mandatory or optional | |
fa83cc83 SG |
11 | 'non-option arguments', e.g. a filename or a branch, 'options', and |
12 | 'subcommands'. | |
224712e5 SB |
13 | Options are optional arguments that start with a dash and |
14 | that allow to change the behavior of a command. | |
15 | ||
16 | * There are basically three types of options: | |
17 | 'boolean' options, | |
18 | options with (mandatory) 'arguments' and | |
19 | options with 'optional arguments' | |
20 | (i.e. a boolean option that can be adjusted). | |
21 | ||
22 | * There are basically two forms of options: | |
23 | 'Short options' consist of one dash (`-`) and one alphanumeric | |
24 | character. | |
6cf378f0 | 25 | 'Long options' begin with two dashes (`--`) and some |
224712e5 SB |
26 | alphanumeric characters. |
27 | ||
28 | * Options are case-sensitive. | |
29 | Please define 'lower-case long options' only. | |
30 | ||
31 | The parse-options API allows: | |
32 | ||
b0d12fc9 NV |
33 | * 'stuck' and 'separate form' of options with arguments. |
34 | `-oArg` is stuck, `-o Arg` is separate form. | |
35 | `--option=Arg` is stuck, `--option Arg` is separate form. | |
224712e5 SB |
36 | |
37 | * Long options may be 'abbreviated', as long as the abbreviation | |
38 | is unambiguous. | |
39 | ||
40 | * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. | |
41 | ||
42 | * Boolean long options can be 'negated' (or 'unset') by prepending | |
6cf378f0 | 43 | `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, |
0f1930c5 | 44 | options that begin with `no-` can be 'negated' by removing it. |
8a09e6c5 MH |
45 | Other long options can be unset (e.g., set string to NULL, set |
46 | integer to 0) by prepending `no-`. | |
224712e5 | 47 | |
6cf378f0 JK |
48 | * Options and non-option arguments can clearly be separated using the `--` |
49 | option, e.g. `-a -b --option -- --this-is-a-file` indicates that | |
50 | `--this-is-a-file` must not be processed as an option. | |
224712e5 | 51 | |
fa83cc83 SG |
52 | Subcommands are special in a couple of ways: |
53 | ||
54 | * Subcommands only have long form, and they have no double dash prefix, no | |
55 | negated form, and no description, and they don't take any arguments, and | |
56 | can't be abbreviated. | |
57 | ||
58 | * There must be exactly one subcommand among the arguments, or zero if the | |
59 | command has a default operation mode. | |
60 | ||
61 | * All arguments following the subcommand are considered to be arguments of | |
62 | the subcommand, and, conversely, arguments meant for the subcommand may | |
bbb0c357 | 63 | not precede the subcommand. |
fa83cc83 SG |
64 | |
65 | Therefore, if the options array contains at least one subcommand and | |
66 | `parse_options()` encounters the first dashless argument, it will either: | |
67 | ||
68 | * stop and return, if that dashless argument is a known subcommand, setting | |
69 | `value` to the function pointer associated with that subcommand, storing | |
70 | the name of the subcommand in argv[0], and leaving the rest of the | |
71 | arguments unprocessed, or | |
72 | ||
73 | * stop and return, if it was invoked with the `PARSE_OPT_SUBCOMMAND_OPTIONAL` | |
74 | flag and that dashless argument doesn't match any subcommands, leaving | |
75 | `value` unchanged and the rest of the arguments unprocessed, or | |
76 | ||
77 | * show error and usage, and abort. | |
78 | ||
224712e5 SB |
79 | Steps to parse options |
80 | ---------------------- | |
81 | ||
82 | . `#include "parse-options.h"` | |
83 | ||
84 | . define a NULL-terminated | |
85 | `static const char * const builtin_foo_usage[]` array | |
86 | containing alternative usage strings | |
87 | ||
88 | . define `builtin_foo_options` array as described below | |
89 | in section 'Data Structure'. | |
90 | ||
91 | . in `cmd_foo(int argc, const char **argv, const char *prefix)` | |
92 | call | |
93 | ||
37782920 | 94 | argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags); |
224712e5 SB |
95 | + |
96 | `parse_options()` will filter out the processed options of `argv[]` and leave the | |
97 | non-option arguments in `argv[]`. | |
98 | `argc` is updated appropriately because of the assignment. | |
99 | + | |
37782920 | 100 | You can also pass NULL instead of a usage array as the fifth parameter of |
9ad7e6ea RS |
101 | parse_options(), to avoid displaying a help screen with usage info and |
102 | option list. This should only be done if necessary, e.g. to implement | |
103 | a limited parser for only a subset of the options that needs to be run | |
104 | before the full parser, which in turn shows the full help message. | |
105 | + | |
224712e5 SB |
106 | Flags are the bitwise-or of: |
107 | ||
108 | `PARSE_OPT_KEEP_DASHDASH`:: | |
6cf378f0 | 109 | Keep the `--` that usually separates options from |
224712e5 SB |
110 | non-option arguments. |
111 | ||
112 | `PARSE_OPT_STOP_AT_NON_OPTION`:: | |
113 | Usually the whole argument vector is massaged and reordered. | |
114 | Using this flag, processing is stopped at the first non-option | |
115 | argument. | |
116 | ||
9ad7e6ea RS |
117 | `PARSE_OPT_KEEP_ARGV0`:: |
118 | Keep the first argument, which contains the program name. It's | |
119 | removed from argv[] by default. | |
120 | ||
99d86d60 SG |
121 | `PARSE_OPT_KEEP_UNKNOWN_OPT`:: |
122 | Keep unknown options instead of erroring out. This doesn't | |
9ad7e6ea RS |
123 | work for all combinations of arguments as users might expect |
124 | it to do. E.g. if the first argument in `--unknown --known` | |
125 | takes a value (which we can't know), the second one is | |
126 | mistakenly interpreted as a known option. Similarly, if | |
127 | `PARSE_OPT_STOP_AT_NON_OPTION` is set, the second argument in | |
128 | `--unknown value` will be mistakenly interpreted as a | |
129 | non-option, not as a value belonging to the unknown option, | |
0d260f9a RS |
130 | the parser early. That's why parse_options() errors out if |
131 | both options are set. | |
99d86d60 SG |
132 | Note that non-option arguments are always kept, even without |
133 | this flag. | |
9ad7e6ea RS |
134 | |
135 | `PARSE_OPT_NO_INTERNAL_HELP`:: | |
136 | By default, parse_options() handles `-h`, `--help` and | |
137 | `--help-all` internally, by showing a help screen. This option | |
138 | turns it off and allows one to add custom handlers for these | |
139 | options, or to just leave them unknown. | |
140 | ||
fa83cc83 SG |
141 | `PARSE_OPT_SUBCOMMAND_OPTIONAL`:: |
142 | Don't error out when no subcommand is specified. | |
143 | ||
144 | Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands; | |
145 | while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be | |
146 | used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`. | |
147 | ||
224712e5 SB |
148 | Data Structure |
149 | -------------- | |
150 | ||
151 | The main data structure is an array of the `option` struct, | |
152 | say `static struct option builtin_add_options[]`. | |
153 | There are some macros to easily define options: | |
154 | ||
155 | `OPT__ABBREV(&int_var)`:: | |
6cf378f0 | 156 | Add `--abbrev[=<n>]`. |
224712e5 | 157 | |
73e9da01 | 158 | `OPT__COLOR(&int_var, description)`:: |
6cf378f0 | 159 | Add `--color[=<when>]` and `--no-color`. |
73e9da01 | 160 | |
e21adb8c | 161 | `OPT__DRY_RUN(&int_var, description)`:: |
6cf378f0 | 162 | Add `-n, --dry-run`. |
224712e5 | 163 | |
76946b76 | 164 | `OPT__FORCE(&int_var, description)`:: |
6cf378f0 | 165 | Add `-f, --force`. |
76946b76 | 166 | |
d52ee6e6 | 167 | `OPT__QUIET(&int_var, description)`:: |
6cf378f0 | 168 | Add `-q, --quiet`. |
224712e5 | 169 | |
fd03881a | 170 | `OPT__VERBOSE(&int_var, description)`:: |
6cf378f0 | 171 | Add `-v, --verbose`. |
224712e5 SB |
172 | |
173 | `OPT_GROUP(description)`:: | |
174 | Start an option group. `description` is a short string that | |
175 | describes the group or an empty string. | |
176 | Start the description with an upper-case letter. | |
177 | ||
b04ba2bb JH |
178 | `OPT_BOOL(short, long, &int_var, description)`:: |
179 | Introduce a boolean option. `int_var` is set to one with | |
180 | `--option` and set to zero with `--no-option`. | |
181 | ||
182 | `OPT_COUNTUP(short, long, &int_var, description)`:: | |
183 | Introduce a count-up option. | |
e0070e8b PB |
184 | Each use of `--option` increments `int_var`, starting from zero |
185 | (even if initially negative), and `--no-option` resets it to | |
186 | zero. To determine if `--option` or `--no-option` was encountered at | |
187 | all, initialize `int_var` to a negative value, and if it is still | |
188 | negative after parse_options(), then neither `--option` nor | |
189 | `--no-option` was seen. | |
224712e5 SB |
190 | |
191 | `OPT_BIT(short, long, &int_var, description, mask)`:: | |
192 | Introduce a boolean option. | |
193 | If used, `int_var` is bitwise-ored with `mask`. | |
194 | ||
2f4b97f9 RS |
195 | `OPT_NEGBIT(short, long, &int_var, description, mask)`:: |
196 | Introduce a boolean option. | |
197 | If used, `int_var` is bitwise-anded with the inverted `mask`. | |
198 | ||
224712e5 | 199 | `OPT_SET_INT(short, long, &int_var, description, integer)`:: |
b04ba2bb JH |
200 | Introduce an integer option. |
201 | `int_var` is set to `integer` with `--option`, and | |
202 | reset to zero with `--no-option`. | |
224712e5 | 203 | |
224712e5 SB |
204 | `OPT_STRING(short, long, &str_var, arg_str, description)`:: |
205 | Introduce an option with string argument. | |
206 | The string argument is put into `str_var`. | |
207 | ||
4a687488 JK |
208 | `OPT_STRING_LIST(short, long, &struct string_list, arg_str, description)`:: |
209 | Introduce an option with string argument. | |
210 | The string argument is stored as an element in `string_list`. | |
211 | Use of `--no-option` will clear the list of preceding values. | |
212 | ||
224712e5 SB |
213 | `OPT_INTEGER(short, long, &int_var, description)`:: |
214 | Introduce an option with integer argument. | |
215 | The integer is put into `int_var`. | |
216 | ||
2a514ed8 CB |
217 | `OPT_MAGNITUDE(short, long, &unsigned_long_var, description)`:: |
218 | Introduce an option with a size argument. The argument must be a | |
219 | non-negative integer and may include a suffix of 'k', 'm' or 'g' to | |
220 | scale the provided value by 1024, 1024^2 or 1024^3 respectively. | |
221 | The scaled value is put into `unsigned_long_var`. | |
222 | ||
dddbad72 | 223 | `OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`:: |
27ec394a | 224 | Introduce an option with expiry date argument, see `parse_expiry_date()`. |
dddbad72 | 225 | The timestamp is put into `timestamp_t_var`. |
27ec394a | 226 | |
224712e5 SB |
227 | `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: |
228 | Introduce an option with argument. | |
229 | The argument will be fed into the function given by `func_ptr` | |
230 | and the result will be put into `var`. | |
231 | See 'Option Callbacks' below for a more elaborate description. | |
232 | ||
df217ed6 SB |
233 | `OPT_FILENAME(short, long, &var, description)`:: |
234 | Introduce an option with a filename argument. | |
235 | The filename will be prefixed by passing the filename along with | |
236 | the prefix argument of `parse_options()` to `prefix_filename()`. | |
237 | ||
e0319ff5 RS |
238 | `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: |
239 | Recognize numerical options like -123 and feed the integer as | |
240 | if it was an argument to the function given by `func_ptr`. | |
241 | The result will be put into `var`. There can be only one such | |
242 | option definition. It cannot be negated and it takes no | |
243 | arguments. Short options that happen to be digits take | |
244 | precedence over it. | |
245 | ||
73e9da01 ML |
246 | `OPT_COLOR_FLAG(short, long, &int_var, description)`:: |
247 | Introduce an option that takes an optional argument that can | |
248 | have one of three values: "always", "never", or "auto". If the | |
249 | argument is not given, it defaults to "always". The `--no-` form | |
250 | works like `--long=never`; it cannot take an argument. If | |
251 | "always", set `int_var` to 1; if "never", set `int_var` to 0; if | |
252 | "auto", set `int_var` to 1 if stdout is a tty or a pager, | |
253 | 0 otherwise. | |
254 | ||
6acec038 RS |
255 | `OPT_NOOP_NOARG(short, long)`:: |
256 | Introduce an option that has no effect and takes no arguments. | |
257 | Use it to hide deprecated options that are still to be recognized | |
258 | and ignored silently. | |
259 | ||
6b3ee18d PT |
260 | `OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`:: |
261 | Introduce an option that will be reconstructed into a char* string, | |
262 | which must be initialized to NULL. This is useful when you need to | |
263 | pass the command-line option to another command. Any previous value | |
264 | will be overwritten, so this should only be used for options where | |
265 | the last one specified on the command line wins. | |
266 | ||
837dc425 | 267 | `OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`:: |
ffad85c5 | 268 | Introduce an option where all instances of it on the command-line will |
837dc425 | 269 | be reconstructed into a strvec. This is useful when you need to |
ffad85c5 PT |
270 | pass the command-line option, which can be specified multiple times, |
271 | to another command. | |
272 | ||
c3f6b853 PB |
273 | `OPT_CMDMODE(short, long, &int_var, description, enum_val)`:: |
274 | Define an "operation mode" option, only one of which in the same | |
275 | group of "operating mode" options that share the same `int_var` | |
80882bc5 | 276 | can be given by the user. `int_var` is set to `enum_val` when the |
c3f6b853 PB |
277 | option is used, but an error is reported if other "operating mode" |
278 | option has already set its value to the same `int_var`. | |
fa83cc83 | 279 | In new commands consider using subcommands instead. |
c3f6b853 | 280 | |
fa83cc83 SG |
281 | `OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`:: |
282 | Define a subcommand. `subcommand_fn` is put into `fn_ptr` when | |
283 | this subcommand is used. | |
224712e5 SB |
284 | |
285 | The last element of the array must be `OPT_END()`. | |
286 | ||
287 | If not stated otherwise, interpret the arguments as follows: | |
288 | ||
289 | * `short` is a character for the short option | |
6cf378f0 | 290 | (e.g. `'e'` for `-e`, use `0` to omit), |
224712e5 SB |
291 | |
292 | * `long` is a string for the long option | |
6cf378f0 | 293 | (e.g. `"example"` for `--example`, use `NULL` to omit), |
224712e5 SB |
294 | |
295 | * `int_var` is an integer variable, | |
296 | ||
297 | * `str_var` is a string variable (`char *`), | |
298 | ||
299 | * `arg_str` is the string that is shown as argument | |
300 | (e.g. `"branch"` will result in `<branch>`). | |
301 | If set to `NULL`, three dots (`...`) will be displayed. | |
302 | ||
303 | * `description` is a short string to describe the effect of the option. | |
304 | It shall begin with a lower-case letter and a full stop (`.`) shall be | |
305 | omitted at the end. | |
306 | ||
307 | Option Callbacks | |
308 | ---------------- | |
309 | ||
310 | The function must be defined in this form: | |
311 | ||
312 | int func(const struct option *opt, const char *arg, int unset) | |
313 | ||
314 | The callback mechanism is as follows: | |
315 | ||
ca156cfc | 316 | * Inside `func`, the only interesting member of the structure |
6cf378f0 JK |
317 | given by `opt` is the void pointer `opt->value`. |
318 | `*opt->value` will be the value that is saved into `var`, if you | |
224712e5 | 319 | use `OPT_CALLBACK()`. |
6cf378f0 | 320 | For example, do `*(unsigned long *)opt->value = 42;` to get 42 |
224712e5 SB |
321 | into an `unsigned long` variable. |
322 | ||
323 | * Return value `0` indicates success and non-zero return | |
324 | value will invoke `usage_with_options()` and, thus, die. | |
325 | ||
326 | * If the user negates the option, `arg` is `NULL` and `unset` is 1. | |
327 | ||
328 | Sophisticated option parsing | |
329 | ---------------------------- | |
330 | ||
331 | If you need, for example, option callbacks with optional arguments | |
332 | or without arguments at all, or if you need other special cases, | |
333 | that are not handled by the macros above, you need to specify the | |
334 | members of the `option` structure manually. | |
335 | ||
336 | This is not covered in this document, but well documented | |
337 | in `parse-options.h` itself. | |
338 | ||
339 | Examples | |
340 | -------- | |
341 | ||
342 | See `test-parse-options.c` and | |
09b7e220 PH |
343 | `builtin/add.c`, |
344 | `builtin/clone.c`, | |
345 | `builtin/commit.c`, | |
346 | `builtin/fetch.c`, | |
347 | `builtin/fsck.c`, | |
348 | `builtin/rm.c` | |
224712e5 | 349 | for real-world examples. |