api-parse-options.txt: Introduce documentation for parse options API
Add some documentation of basics, macros and callback implementation of the parse-options API. Signed-off-by: Stephan Beyer <s-beyer@gmx.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Stephan Beyer committed
Jun 22, 2008 at 17:04 UTC
224712e521c6d4f740045affa4d1ee1454db10d4
1 file changed
+202
-2
Documentation/technical/api-parse-options.txt
+202
-2
@@ -1,6 +1,206 @@
1
parse-options API
2
=================
3
4
-Talk about <parse-options.h>
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
6
-(Pierre)
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
++
69
+Flags are the bitwise-or of:
70
+
71
+`PARSE_OPT_KEEP_DASHDASH`::
72
+ Keep the `\--` that usually separates options from
73
+ non-option arguments.
74
+
75
+`PARSE_OPT_STOP_AT_NON_OPTION`::
76
+ Usually the whole argument vector is massaged and reordered.
77
+ Using this flag, processing is stopped at the first non-option
78
+ argument.
79
+
80
+Data Structure
81
+--------------
82
+
83
+The main data structure is an array of the `option` struct,
84
+say `static struct option builtin_add_options[]`.
85
+There are some macros to easily define options:
86
+
87
+`OPT__ABBREV(&int_var)`::
88
+ Add `\--abbrev[=<n>]`.
89
+
90
+`OPT__DRY_RUN(&int_var)`::
91
+ Add `-n, \--dry-run`.
92
+
93
+`OPT__QUIET(&int_var)`::
94
+ Add `-q, \--quiet`.
95
+
96
+`OPT__VERBOSE(&int_var)`::
97
+ Add `-v, \--verbose`.
98
+
99
+`OPT_GROUP(description)`::
100
+ Start an option group. `description` is a short string that
101
+ describes the group or an empty string.
102
+ Start the description with an upper-case letter.
103
+
104
+`OPT_BOOLEAN(short, long, &int_var, description)`::
105
+ Introduce a boolean option.
106
+ `int_var` is incremented on each use.
107
+
108
+`OPT_BIT(short, long, &int_var, description, mask)`::
109
+ Introduce a boolean option.
110
+ If used, `int_var` is bitwise-ored with `mask`.
111
+
112
+`OPT_SET_INT(short, long, &int_var, description, integer)`::
113
+ Introduce a boolean option.
114
+ If used, set `int_var` to `integer`.
115
+
116
+`OPT_SET_PTR(short, long, &ptr_var, description, ptr)`::
117
+ Introduce a boolean option.
118
+ If used, set `ptr_var` to `ptr`.
119
+
120
+`OPT_STRING(short, long, &str_var, arg_str, description)`::
121
+ Introduce an option with string argument.
122
+ The string argument is put into `str_var`.
123
+
124
+`OPT_INTEGER(short, long, &int_var, description)`::
125
+ Introduce an option with integer argument.
126
+ The integer is put into `int_var`.
127
+
128
+`OPT_DATE(short, long, &int_var, description)`::
129
+ Introduce an option with date argument, see `approxidate()`.
130
+ The timestamp is put into `int_var`.
131
+
132
+`OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`::
133
+ Introduce an option with argument.
134
+ The argument will be fed into the function given by `func_ptr`
135
+ and the result will be put into `var`.
136
+ See 'Option Callbacks' below for a more elaborate description.
137
+
138
+`OPT_ARGUMENT(long, description)`::
139
+ Introduce a long-option argument that will be kept in `argv[]`.
140
+
141
+
142
+The last element of the array must be `OPT_END()`.
143
+
144
+If not stated otherwise, interpret the arguments as follows:
145
+
146
+* `short` is a character for the short option
147
+ (e.g. `\'e\'` for `-e`, use `0` to omit),
148
+
149
+* `long` is a string for the long option
150
+ (e.g. `"example"` for `\--example`, use `NULL` to omit),
151
+
152
+* `int_var` is an integer variable,
153
+
154
+* `str_var` is a string variable (`char *`),
155
+
156
+* `arg_str` is the string that is shown as argument
157
+ (e.g. `"branch"` will result in `<branch>`).
158
+ If set to `NULL`, three dots (`...`) will be displayed.
159
+
160
+* `description` is a short string to describe the effect of the option.
161
+ It shall begin with a lower-case letter and a full stop (`.`) shall be
162
+ omitted at the end.
163
+
164
+Option Callbacks
165
+----------------
166
+
167
+The function must be defined in this form:
168
+
169
+ int func(const struct option *opt, const char *arg, int unset)
170
+
171
+The callback mechanism is as follows:
172
+
173
+* Inside `funct`, the only interesting member of the structure
174
+ given by `opt` is the void pointer `opt->value`.
175
+ `\*opt->value` will be the value that is saved into `var`, if you
176
+ use `OPT_CALLBACK()`.
177
+ For example, do `*(unsigned long *)opt->value = 42;` to get 42
178
+ into an `unsigned long` variable.
179
+
180
+* Return value `0` indicates success and non-zero return
181
+ value will invoke `usage_with_options()` and, thus, die.
182
+
183
+* If the user negates the option, `arg` is `NULL` and `unset` is 1.
184
+
185
+Sophisticated option parsing
186
+----------------------------
187
+
188
+If you need, for example, option callbacks with optional arguments
189
+or without arguments at all, or if you need other special cases,
190
+that are not handled by the macros above, you need to specify the
191
+members of the `option` structure manually.
192
+
193
+This is not covered in this document, but well documented
194
+in `parse-options.h` itself.
195
+
196
+Examples
197
+--------
198
+
199
+See `test-parse-options.c` and
200
+`builtin-add.c`,
201
+`builtin-clone.c`,
202
+`builtin-commit.c`,
203
+`builtin-fetch.c`,
204
+`builtin-fsck.c`,
205
+`builtin-rm.c`
206
+for real-world examples.