Win32 dirent: clarify #include directives
[git/mingw/4msysgit/gitPS1fix.git] / Documentation / technical / api-parse-options.txt
blobf6a4a361bd56e1cc0f4645e09898e6852bfb8a8b
1 parse-options API
2 =================
4 The parse-options API is used to parse and massage options in git
5 and to provide a usage help with consistent look.
7 Basics
8 ------
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.
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).
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.
27 * Options are case-sensitive.
28   Please define 'lower-case long options' only.
30 The parse-options API allows:
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.
36 * Long options may be 'abbreviated', as long as the abbreviation
37   is unambiguous.
39 * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`.
41 * Boolean long options can be 'negated' (or 'unset') by prepending
42   `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`.
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.
48 Steps to parse options
49 ----------------------
51 . `#include "parse-options.h"`
53 . define a NULL-terminated
54   `static const char * const builtin_foo_usage[]` array
55   containing alternative usage strings
57 . define `builtin_foo_options` array as described below
58   in section 'Data Structure'.
60 . in `cmd_foo(int argc, const char **argv, const char *prefix)`
61   call
63         argc = parse_options(argc, argv, prefix, builtin_foo_options, builtin_foo_usage, flags);
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.
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.
75 Flags are the bitwise-or of:
77 `PARSE_OPT_KEEP_DASHDASH`::
78         Keep the `\--` that usually separates options from
79         non-option arguments.
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.
86 `PARSE_OPT_KEEP_ARGV0`::
87         Keep the first argument, which contains the program name.  It's
88         removed from argv[] by default.
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.
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.
108 Data Structure
109 --------------
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:
115 `OPT__ABBREV(&int_var)`::
116         Add `\--abbrev[=<n>]`.
118 `OPT__COLOR(&int_var, description)`::
119         Add `\--color[=<when>]` and `--no-color`.
121 `OPT__DRY_RUN(&int_var, description)`::
122         Add `-n, \--dry-run`.
124 `OPT__FORCE(&int_var, description)`::
125         Add `-f, \--force`.
127 `OPT__QUIET(&int_var, description)`::
128         Add `-q, \--quiet`.
130 `OPT__VERBOSE(&int_var, description)`::
131         Add `-v, \--verbose`.
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.
138 `OPT_BOOLEAN(short, long, &int_var, description)`::
139         Introduce a boolean option.
140         `int_var` is incremented on each use.
142 `OPT_BIT(short, long, &int_var, description, mask)`::
143         Introduce a boolean option.
144         If used, `int_var` is bitwise-ored with `mask`.
146 `OPT_NEGBIT(short, long, &int_var, description, mask)`::
147         Introduce a boolean option.
148         If used, `int_var` is bitwise-anded with the inverted `mask`.
150 `OPT_SET_INT(short, long, &int_var, description, integer)`::
151         Introduce a boolean option.
152         If used, set `int_var` to `integer`.
154 `OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
155         Introduce a boolean option.
156         If used, set `ptr_var` to `ptr`.
158 `OPT_STRING(short, long, &str_var, arg_str, description)`::
159         Introduce an option with string argument.
160         The string argument is put into `str_var`.
162 `OPT_INTEGER(short, long, &int_var, description)`::
163         Introduce an option with integer argument.
164         The integer is put into `int_var`.
166 `OPT_DATE(short, long, &int_var, description)`::
167         Introduce an option with date argument, see `approxidate()`.
168         The timestamp is put into `int_var`.
170 `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
171         Introduce an option with argument.
172         The argument will be fed into the function given by `func_ptr`
173         and the result will be put into `var`.
174         See 'Option Callbacks' below for a more elaborate description.
176 `OPT_FILENAME(short, long, &var, description)`::
177         Introduce an option with a filename argument.
178         The filename will be prefixed by passing the filename along with
179         the prefix argument of `parse_options()` to `prefix_filename()`.
181 `OPT_ARGUMENT(long, description)`::
182         Introduce a long-option argument that will be kept in `argv[]`.
184 `OPT_NUMBER_CALLBACK(&var, description, func_ptr)`::
185         Recognize numerical options like -123 and feed the integer as
186         if it was an argument to the function given by `func_ptr`.
187         The result will be put into `var`.  There can be only one such
188         option definition.  It cannot be negated and it takes no
189         arguments.  Short options that happen to be digits take
190         precedence over it.
192 `OPT_COLOR_FLAG(short, long, &int_var, description)`::
193         Introduce an option that takes an optional argument that can
194         have one of three values: "always", "never", or "auto".  If the
195         argument is not given, it defaults to "always".  The `--no-` form
196         works like `--long=never`; it cannot take an argument.  If
197         "always", set `int_var` to 1; if "never", set `int_var` to 0; if
198         "auto", set `int_var` to 1 if stdout is a tty or a pager,
199         0 otherwise.
202 The last element of the array must be `OPT_END()`.
204 If not stated otherwise, interpret the arguments as follows:
206 * `short` is a character for the short option
207   (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit),
209 * `long` is a string for the long option
210   (e.g. `"example"` for `\--example`, use `NULL` to omit),
212 * `int_var` is an integer variable,
214 * `str_var` is a string variable (`char *`),
216 * `arg_str` is the string that is shown as argument
217   (e.g. `"branch"` will result in `<branch>`).
218   If set to `NULL`, three dots (`...`) will be displayed.
220 * `description` is a short string to describe the effect of the option.
221   It shall begin with a lower-case letter and a full stop (`.`) shall be
222   omitted at the end.
224 Option Callbacks
225 ----------------
227 The function must be defined in this form:
229         int func(const struct option *opt, const char *arg, int unset)
231 The callback mechanism is as follows:
233 * Inside `func`, the only interesting member of the structure
234   given by `opt` is the void pointer `opt\->value`.
235   `\*opt\->value` will be the value that is saved into `var`, if you
236   use `OPT_CALLBACK()`.
237   For example, do `*(unsigned long *)opt\->value = 42;` to get 42
238   into an `unsigned long` variable.
240 * Return value `0` indicates success and non-zero return
241   value will invoke `usage_with_options()` and, thus, die.
243 * If the user negates the option, `arg` is `NULL` and `unset` is 1.
245 Sophisticated option parsing
246 ----------------------------
248 If you need, for example, option callbacks with optional arguments
249 or without arguments at all, or if you need other special cases,
250 that are not handled by the macros above, you need to specify the
251 members of the `option` structure manually.
253 This is not covered in this document, but well documented
254 in `parse-options.h` itself.
256 Examples
257 --------
259 See `test-parse-options.c` and
260 `builtin-add.c`,
261 `builtin-clone.c`,
262 `builtin-commit.c`,
263 `builtin-fetch.c`,
264 `builtin-fsck.c`,
265 `builtin-rm.c`
266 for real-world examples.