freshlybakedca.ke
Git fork
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, 'options', and
12'subcommands'.
13Options are optional arguments that start with a dash and
14that 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.
25 'Long options' begin with two dashes (`--`) and some
26 alphanumeric characters.
27
28* Options are case-sensitive.
29 Please define 'lower-case long options' only.
30
31The parse-options API allows:
32
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.
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
43 `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely,
44 options that begin with `no-` can be 'negated' by removing it.
45 Other long options can be unset (e.g., set string to NULL, set
46 integer to 0) by prepending `no-`.
47
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.
51
52Subcommands 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
63 not precede the subcommand.
64
65Therefore, 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
79Steps 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
94 argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
95+
96`parse_options()` will filter out the processed options of `argv[]` and leave the
97non-option arguments in `argv[]`.
98`argc` is updated appropriately because of the assignment.
99+
100You can also pass NULL instead of a usage array as the fifth parameter of
101parse_options(), to avoid displaying a help screen with usage info and
102option list. This should only be done if necessary, e.g. to implement
103a limited parser for only a subset of the options that needs to be run
104before the full parser, which in turn shows the full help message.
105+
106Flags are the bitwise-or of:
107
108`PARSE_OPT_KEEP_DASHDASH`::
109 Keep the `--` that usually separates options from
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
117`PARSE_OPT_KEEP_ARGV0`::
118 Keep the first argument, which contains the program name. It's
119 removed from argv[] by default.
120
121`PARSE_OPT_KEEP_UNKNOWN_OPT`::
122 Keep unknown options instead of erroring out. This doesn't
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,
130 the parser early. That's why parse_options() errors out if
131 both options are set.
132 Note that non-option arguments are always kept, even without
133 this flag.
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
141`PARSE_OPT_SUBCOMMAND_OPTIONAL`::
142 Don't error out when no subcommand is specified.
143
144Note that `PARSE_OPT_STOP_AT_NON_OPTION` is incompatible with subcommands;
145while `PARSE_OPT_KEEP_DASHDASH` and `PARSE_OPT_KEEP_UNKNOWN_OPT` can only be
146used with subcommands when combined with `PARSE_OPT_SUBCOMMAND_OPTIONAL`.
147
148Data Structure
149--------------
150
151The main data structure is an array of the `option` struct,
152say `static struct option builtin_add_options[]`.
153There are some macros to easily define options:
154
155`OPT__ABBREV(&int_var)`::
156 Add `--abbrev[=<n>]`.
157
158`OPT__COLOR(&int_var, description)`::
159 Add `--color[=<when>]` and `--no-color`.
160
161`OPT__DRY_RUN(&int_var, description)`::
162 Add `-n, --dry-run`.
163
164`OPT__FORCE(&int_var, description)`::
165 Add `-f, --force`.
166
167`OPT__QUIET(&int_var, description)`::
168 Add `-q, --quiet`.
169
170`OPT__VERBOSE(&int_var, description)`::
171 Add `-v, --verbose`.
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
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.
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.
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
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
199`OPT_SET_INT(short, long, &int_var, description, integer)`::
200 Introduce an integer option.
201 `int_var` is set to `integer` with `--option`, and
202 reset to zero with `--no-option`.
203
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
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
213`OPT_INTEGER(short, long, &int_var, description)`::
214 Introduce an option with integer argument. The argument must be a
215 integer and may include a suffix of 'k', 'm' or 'g' to
216 scale the provided value by 1024, 1024^2 or 1024^3 respectively.
217 The scaled value is put into `int_var`.
218
219`OPT_UNSIGNED(short, long, &unsigned_long_var, description)`::
220 Introduce an option with an unsigned integer argument. The argument must be a
221 non-negative integer and may include a suffix of 'k', 'm' or 'g' to
222 scale the provided value by 1024, 1024^2 or 1024^3 respectively.
223 The scaled value is put into `unsigned_long_var`.
224
225`OPT_EXPIRY_DATE(short, long, ×tamp_t_var, description)`::
226 Introduce an option with expiry date argument, see `parse_expiry_date()`.
227 The timestamp is put into `timestamp_t_var`.
228
229`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
230 Introduce an option with argument.
231 The argument will be fed into the function given by `func_ptr`
232 and the result will be put into `var`.
233 See 'Option Callbacks' below for a more elaborate description.
234
235`OPT_FILENAME(short, long, &var, description)`::
236 Introduce an option with a filename argument.
237 The filename will be prefixed by passing the filename along with
238 the prefix argument of `parse_options()` to `prefix_filename()`.
239
240`OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
241 Recognize numerical options like -123 and feed the integer as
242 if it was an argument to the function given by `func_ptr`.
243 The result will be put into `var`. There can be only one such
244 option definition. It cannot be negated and it takes no
245 arguments. Short options that happen to be digits take
246 precedence over it.
247
248`OPT_COLOR_FLAG(short, long, &int_var, description)`::
249 Introduce an option that takes an optional argument that can
250 have one of three values: "always", "never", or "auto". If the
251 argument is not given, it defaults to "always". The `--no-` form
252 works like `--long=never`; it cannot take an argument. If
253 "always", set `int_var` to 1; if "never", set `int_var` to 0; if
254 "auto", set `int_var` to 1 if stdout is a tty or a pager,
255 0 otherwise.
256
257`OPT_NOOP_NOARG(short, long)`::
258 Introduce an option that has no effect and takes no arguments.
259 Use it to hide deprecated options that are still to be recognized
260 and ignored silently.
261
262`OPT_PASSTHRU(short, long, &char_var, arg_str, description, flags)`::
263 Introduce an option that will be reconstructed into a char* string,
264 which must be initialized to NULL. This is useful when you need to
265 pass the command-line option to another command. Any previous value
266 will be overwritten, so this should only be used for options where
267 the last one specified on the command line wins.
268
269`OPT_PASSTHRU_ARGV(short, long, &strvec_var, arg_str, description, flags)`::
270 Introduce an option where all instances of it on the command-line will
271 be reconstructed into a strvec. This is useful when you need to
272 pass the command-line option, which can be specified multiple times,
273 to another command.
274
275`OPT_CMDMODE(short, long, &int_var, description, enum_val)`::
276 Define an "operation mode" option, only one of which in the same
277 group of "operating mode" options that share the same `int_var`
278 can be given by the user. `int_var` is set to `enum_val` when the
279 option is used, but an error is reported if other "operating mode"
280 option has already set its value to the same `int_var`.
281 In new commands consider using subcommands instead.
282
283`OPT_SUBCOMMAND(long, &fn_ptr, subcommand_fn)`::
284 Define a subcommand. `subcommand_fn` is put into `fn_ptr` when
285 this subcommand is used.
286
287The last element of the array must be `OPT_END()`.
288
289If not stated otherwise, interpret the arguments as follows:
290
291* `short` is a character for the short option
292 (e.g. `'e'` for `-e`, use `0` to omit),
293
294* `long` is a string for the long option
295 (e.g. `"example"` for `--example`, use `NULL` to omit),
296
297* `int_var` is an integer variable,
298
299* `str_var` is a string variable (`char *`),
300
301* `arg_str` is the string that is shown as argument
302 (e.g. `"branch"` will result in `<branch>`).
303 If set to `NULL`, three dots (`...`) will be displayed.
304
305* `description` is a short string to describe the effect of the option.
306 It shall begin with a lower-case letter and a full stop (`.`) shall be
307 omitted at the end.
308
309Option Callbacks
310----------------
311
312The function must be defined in this form:
313
314 int func(const struct option *opt, const char *arg, int unset)
315
316The callback mechanism is as follows:
317
318* Inside `func`, the only interesting member of the structure
319 given by `opt` is the void pointer `opt->value`.
320 `*opt->value` will be the value that is saved into `var`, if you
321 use `OPT_CALLBACK()`.
322 For example, do `*(unsigned long *)opt->value = 42;` to get 42
323 into an `unsigned long` variable.
324
325* Return value `0` indicates success and non-zero return
326 value will invoke `usage_with_options()` and, thus, die.
327
328* If the user negates the option, `arg` is `NULL` and `unset` is 1.
329
330Sophisticated option parsing
331----------------------------
332
333If you need, for example, option callbacks with optional arguments
334or without arguments at all, or if you need other special cases,
335that are not handled by the macros above, you need to specify the
336members of the `option` structure manually.
337
338This is not covered in this document, but well documented
339in `parse-options.h` itself.
340
341Examples
342--------
343
344See `test-parse-options.c` and
345`builtin/add.c`,
346`builtin/clone.c`,
347`builtin/commit.c`,
348`builtin/fetch.c`,
349`builtin/fsck.c`,
350`builtin/rm.c`
351for real-world examples.