]>
Commit | Line | Data |
---|---|---|
530e741c JH |
1 | parse-options API |
2 | ================= | |
3 | ||
224712e5 SB |
4 | The parse-options API is used to parse and massage options in git |
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 | |
11 | 'non-option arguments', e.g. a filename or a branch, and 'options'. | |
12 | Options are optional arguments that start with a dash and | |
13 | that 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 | ||
30 | The 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 | ||
48 | Steps 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 | |
66 | non-option arguments in `argv[]`. | |
67 | `argc` is updated appropriately because of the assignment. | |
68 | + | |
9ad7e6ea RS |
69 | You can also pass NULL instead of a usage array as fourth parameter of |
70 | parse_options(), to avoid displaying a help screen with usage info and | |
71 | option list. This should only be done if necessary, e.g. to implement | |
72 | a limited parser for only a subset of the options that needs to be run | |
73 | before the full parser, which in turn shows the full help message. | |
74 | + | |
224712e5 SB |
75 | Flags 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 | ||
9ad7e6ea RS |
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, | |
0d260f9a RS |
99 | the parser early. That's why parse_options() errors out if |
100 | both options are set. | |
9ad7e6ea RS |
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 | ||
224712e5 SB |
108 | Data Structure |
109 | -------------- | |
110 | ||
111 | The main data structure is an array of the `option` struct, | |
112 | say `static struct option builtin_add_options[]`. | |
113 | There are some macros to easily define options: | |
114 | ||
115 | `OPT__ABBREV(&int_var)`:: | |
116 | Add `\--abbrev[=<n>]`. | |
117 | ||
118 | `OPT__DRY_RUN(&int_var)`:: | |
119 | Add `-n, \--dry-run`. | |
120 | ||
121 | `OPT__QUIET(&int_var)`:: | |
122 | Add `-q, \--quiet`. | |
123 | ||
124 | `OPT__VERBOSE(&int_var)`:: | |
125 | Add `-v, \--verbose`. | |
126 | ||
127 | `OPT_GROUP(description)`:: | |
128 | Start an option group. `description` is a short string that | |
129 | describes the group or an empty string. | |
130 | Start the description with an upper-case letter. | |
131 | ||
132 | `OPT_BOOLEAN(short, long, &int_var, description)`:: | |
133 | Introduce a boolean option. | |
134 | `int_var` is incremented on each use. | |
135 | ||
136 | `OPT_BIT(short, long, &int_var, description, mask)`:: | |
137 | Introduce a boolean option. | |
138 | If used, `int_var` is bitwise-ored with `mask`. | |
139 | ||
2f4b97f9 RS |
140 | `OPT_NEGBIT(short, long, &int_var, description, mask)`:: |
141 | Introduce a boolean option. | |
142 | If used, `int_var` is bitwise-anded with the inverted `mask`. | |
143 | ||
224712e5 SB |
144 | `OPT_SET_INT(short, long, &int_var, description, integer)`:: |
145 | Introduce a boolean option. | |
146 | If used, set `int_var` to `integer`. | |
147 | ||
148 | `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`:: | |
149 | Introduce a boolean option. | |
150 | If used, set `ptr_var` to `ptr`. | |
151 | ||
152 | `OPT_STRING(short, long, &str_var, arg_str, description)`:: | |
153 | Introduce an option with string argument. | |
154 | The string argument is put into `str_var`. | |
155 | ||
156 | `OPT_INTEGER(short, long, &int_var, description)`:: | |
157 | Introduce an option with integer argument. | |
158 | The integer is put into `int_var`. | |
159 | ||
160 | `OPT_DATE(short, long, &int_var, description)`:: | |
161 | Introduce an option with date argument, see `approxidate()`. | |
162 | The timestamp is put into `int_var`. | |
163 | ||
164 | `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: | |
165 | Introduce an option with argument. | |
166 | The argument will be fed into the function given by `func_ptr` | |
167 | and the result will be put into `var`. | |
168 | See 'Option Callbacks' below for a more elaborate description. | |
169 | ||
170 | `OPT_ARGUMENT(long, description)`:: | |
171 | Introduce a long-option argument that will be kept in `argv[]`. | |
172 | ||
e0319ff5 RS |
173 | `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`:: |
174 | Recognize numerical options like -123 and feed the integer as | |
175 | if it was an argument to the function given by `func_ptr`. | |
176 | The result will be put into `var`. There can be only one such | |
177 | option definition. It cannot be negated and it takes no | |
178 | arguments. Short options that happen to be digits take | |
179 | precedence over it. | |
180 | ||
224712e5 SB |
181 | |
182 | The last element of the array must be `OPT_END()`. | |
183 | ||
184 | If not stated otherwise, interpret the arguments as follows: | |
185 | ||
186 | * `short` is a character for the short option | |
187 | (e.g. `\'e\'` for `-e`, use `0` to omit), | |
188 | ||
189 | * `long` is a string for the long option | |
190 | (e.g. `"example"` for `\--example`, use `NULL` to omit), | |
191 | ||
192 | * `int_var` is an integer variable, | |
193 | ||
194 | * `str_var` is a string variable (`char *`), | |
195 | ||
196 | * `arg_str` is the string that is shown as argument | |
197 | (e.g. `"branch"` will result in `<branch>`). | |
198 | If set to `NULL`, three dots (`...`) will be displayed. | |
199 | ||
200 | * `description` is a short string to describe the effect of the option. | |
201 | It shall begin with a lower-case letter and a full stop (`.`) shall be | |
202 | omitted at the end. | |
203 | ||
204 | Option Callbacks | |
205 | ---------------- | |
206 | ||
207 | The function must be defined in this form: | |
208 | ||
209 | int func(const struct option *opt, const char *arg, int unset) | |
210 | ||
211 | The callback mechanism is as follows: | |
212 | ||
213 | * Inside `funct`, the only interesting member of the structure | |
214 | given by `opt` is the void pointer `opt->value`. | |
215 | `\*opt->value` will be the value that is saved into `var`, if you | |
216 | use `OPT_CALLBACK()`. | |
217 | For example, do `*(unsigned long *)opt->value = 42;` to get 42 | |
218 | into an `unsigned long` variable. | |
219 | ||
220 | * Return value `0` indicates success and non-zero return | |
221 | value will invoke `usage_with_options()` and, thus, die. | |
222 | ||
223 | * If the user negates the option, `arg` is `NULL` and `unset` is 1. | |
224 | ||
225 | Sophisticated option parsing | |
226 | ---------------------------- | |
227 | ||
228 | If you need, for example, option callbacks with optional arguments | |
229 | or without arguments at all, or if you need other special cases, | |
230 | that are not handled by the macros above, you need to specify the | |
231 | members of the `option` structure manually. | |
232 | ||
233 | This is not covered in this document, but well documented | |
234 | in `parse-options.h` itself. | |
235 | ||
236 | Examples | |
237 | -------- | |
238 | ||
239 | See `test-parse-options.c` and | |
240 | `builtin-add.c`, | |
241 | `builtin-clone.c`, | |
242 | `builtin-commit.c`, | |
243 | `builtin-fetch.c`, | |
244 | `builtin-fsck.c`, | |
245 | `builtin-rm.c` | |
246 | for real-world examples. |