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