parse-options: deprecate OPT_BOOLEAN
[git/git.git] / Documentation / technical / api-parse-options.txt
1 parse-options API
2 =================
3
4 The parse-options API is used to parse and massage options in git
5 and to provide a usage help with consistent look.
6
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, prefix, 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 +
69 You can also pass NULL instead of a usage array as the fifth 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 +
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
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
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__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
208 The last element of the array must be `OPT_END()`.
209
210 If not stated otherwise, interpret the arguments as follows:
211
212 * `short` is a character for the short option
213 (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
214
215 * `long` is a string for the long option
216 (e.g. `"example"` for `\--example`, use `NULL` to omit),
217
218 * `int_var` is an integer variable,
219
220 * `str_var` is a string variable (`char *`),
221
222 * `arg_str` is the string that is shown as argument
223 (e.g. `"branch"` will result in `<branch>`).
224 If set to `NULL`, three dots (`...`) will be displayed.
225
226 * `description` is a short string to describe the effect of the option.
227 It shall begin with a lower-case letter and a full stop (`.`) shall be
228 omitted at the end.
229
230 Option Callbacks
231 ----------------
232
233 The function must be defined in this form:
234
235 int func(const struct option *opt, const char *arg, int unset)
236
237 The callback mechanism is as follows:
238
239 * Inside `func`, the only interesting member of the structure
240 given by `opt` is the void pointer `opt\->value`.
241 `\*opt\->value` will be the value that is saved into `var`, if you
242 use `OPT_CALLBACK()`.
243 For example, do `*(unsigned long *)opt\->value = 42;` to get 42
244 into an `unsigned long` variable.
245
246 * Return value `0` indicates success and non-zero return
247 value will invoke `usage_with_options()` and, thus, die.
248
249 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
250
251 Sophisticated option parsing
252 ----------------------------
253
254 If you need, for example, option callbacks with optional arguments
255 or without arguments at all, or if you need other special cases,
256 that are not handled by the macros above, you need to specify the
257 members of the `option` structure manually.
258
259 This is not covered in this document, but well documented
260 in `parse-options.h` itself.
261
262 Examples
263 --------
264
265 See `test-parse-options.c` and
266 `builtin-add.c`,
267 `builtin-clone.c`,
268 `builtin-commit.c`,
269 `builtin-fetch.c`,
270 `builtin-fsck.c`,
271 `builtin-rm.c`
272 for real-world examples.