parseopt: add PARSE_OPT_KEEP_UNKNOWN
[git/git.git] / parse-options.h
CommitLineData
4a59fd13
PH
1#ifndef PARSE_OPTIONS_H
2#define PARSE_OPTIONS_H
3
4enum parse_opt_type {
db7244bd 5 /* special types */
4a59fd13 6 OPTION_END,
580d5bff 7 OPTION_ARGUMENT,
d7a38c54 8 OPTION_GROUP,
db7244bd
PH
9 /* options with no arguments */
10 OPTION_BIT,
11 OPTION_BOOLEAN, /* _INCR would have been a better name */
12 OPTION_SET_INT,
13 OPTION_SET_PTR,
14 /* options with arguments (usually) */
4a59fd13
PH
15 OPTION_STRING,
16 OPTION_INTEGER,
ffe659f9 17 OPTION_CALLBACK,
4a59fd13
PH
18};
19
20enum parse_opt_flags {
21 PARSE_OPT_KEEP_DASHDASH = 1,
a0ec9d25 22 PARSE_OPT_STOP_AT_NON_OPTION = 2,
a32a4eaa 23 PARSE_OPT_KEEP_ARGV0 = 4,
b5ce3a54 24 PARSE_OPT_KEEP_UNKNOWN = 8,
4a59fd13
PH
25};
26
ffe659f9
PH
27enum parse_opt_option_flags {
28 PARSE_OPT_OPTARG = 1,
f481e22a 29 PARSE_OPT_NOARG = 2,
db7244bd 30 PARSE_OPT_NONEG = 4,
dd3bf0f4 31 PARSE_OPT_HIDDEN = 8,
1cc6985c 32 PARSE_OPT_LASTARG_DEFAULT = 16,
ffe659f9
PH
33};
34
35struct option;
36typedef int parse_opt_cb(const struct option *, const char *arg, int unset);
37
9b3beb58
PH
38/*
39 * `type`::
40 * holds the type of the option, you must have an OPTION_END last in your
41 * array.
42 *
43 * `short_name`::
44 * the character to use as a short option name, '\0' if none.
45 *
46 * `long_name`::
47 * the long option name, without the leading dashes, NULL if none.
48 *
49 * `value`::
50 * stores pointers to the values to be filled.
51 *
52 * `argh`::
53 * token to explain the kind of argument this option wants. Keep it
54 * homogenous across the repository.
55 *
56 * `help`::
57 * the short help associated to what the option does.
58 * Must never be NULL (except for OPTION_END).
59 * OPTION_GROUP uses this pointer to store the group header.
60 *
61 * `flags`::
62 * mask of parse_opt_option_flags.
63 * PARSE_OPT_OPTARG: says that the argument is optionnal (not for BOOLEANs)
64 * PARSE_OPT_NOARG: says that this option takes no argument, for CALLBACKs
db7244bd 65 * PARSE_OPT_NONEG: says that this option cannot be negated
dd3bf0f4
PH
66 * PARSE_OPT_HIDDEN this option is skipped in the default usage, showed in
67 * the long one.
9b3beb58
PH
68 *
69 * `callback`::
70 * pointer to the callback to use for OPTION_CALLBACK.
71 *
72 * `defval`::
73 * default value to fill (*->value) with for PARSE_OPT_OPTARG.
db7244bd
PH
74 * OPTION_{BIT,SET_INT,SET_PTR} store the {mask,integer,pointer} to put in
75 * the value when met.
9b3beb58
PH
76 * CALLBACKS can use it like they want.
77 */
4a59fd13
PH
78struct option {
79 enum parse_opt_type type;
80 int short_name;
81 const char *long_name;
82 void *value;
d7a38c54
PH
83 const char *argh;
84 const char *help;
ffe659f9
PH
85
86 int flags;
87 parse_opt_cb *callback;
ffe659f9 88 intptr_t defval;
4a59fd13
PH
89};
90
91#define OPT_END() { OPTION_END }
580d5bff 92#define OPT_ARGUMENT(l, h) { OPTION_ARGUMENT, 0, (l), NULL, NULL, (h) }
d7a38c54 93#define OPT_GROUP(h) { OPTION_GROUP, 0, NULL, NULL, NULL, (h) }
db7244bd 94#define OPT_BIT(s, l, v, h, b) { OPTION_BIT, (s), (l), (v), NULL, (h), 0, NULL, (b) }
d7a38c54 95#define OPT_BOOLEAN(s, l, v, h) { OPTION_BOOLEAN, (s), (l), (v), NULL, (h) }
db7244bd
PH
96#define OPT_SET_INT(s, l, v, h, i) { OPTION_SET_INT, (s), (l), (v), NULL, (h), 0, NULL, (i) }
97#define OPT_SET_PTR(s, l, v, h, p) { OPTION_SET_PTR, (s), (l), (v), NULL, (h), 0, NULL, (p) }
d7a38c54
PH
98#define OPT_INTEGER(s, l, v, h) { OPTION_INTEGER, (s), (l), (v), NULL, (h) }
99#define OPT_STRING(s, l, v, a, h) { OPTION_STRING, (s), (l), (v), (a), (h) }
1f4a711a
MB
100#define OPT_DATE(s, l, v, h) \
101 { OPTION_CALLBACK, (s), (l), (v), "time",(h), 0, \
102 parse_opt_approxidate_cb }
ffe659f9
PH
103#define OPT_CALLBACK(s, l, v, a, h, f) \
104 { OPTION_CALLBACK, (s), (l), (v), (a), (h), 0, (f) }
4a59fd13
PH
105
106/* parse_options() will filter out the processed options and leave the
107 * non-option argments in argv[].
108 * Returns the number of arguments left in argv[].
109 */
110extern int parse_options(int argc, const char **argv,
111 const struct option *options,
d7a38c54
PH
112 const char * const usagestr[], int flags);
113
114extern NORETURN void usage_with_options(const char * const *usagestr,
115 const struct option *options);
4a59fd13 116
7e7bbcb4
PH
117/*----- incremantal advanced APIs -----*/
118
ee68b87a
PH
119enum {
120 PARSE_OPT_HELP = -1,
121 PARSE_OPT_DONE,
122 PARSE_OPT_UNKNOWN,
123};
124
26141b5b
PH
125/*
126 * It's okay for the caller to consume argv/argc in the usual way.
127 * Other fields of that structure are private to parse-options and should not
128 * be modified in any way.
129 */
7e7bbcb4
PH
130struct parse_opt_ctx_t {
131 const char **argv;
132 const char **out;
133 int argc, cpidx;
134 const char *opt;
135 int flags;
136};
137
ee68b87a
PH
138extern int parse_options_usage(const char * const *usagestr,
139 const struct option *opts);
140
7e7bbcb4
PH
141extern void parse_options_start(struct parse_opt_ctx_t *ctx,
142 int argc, const char **argv, int flags);
143
ff43ec3e
PH
144extern int parse_options_step(struct parse_opt_ctx_t *ctx,
145 const struct option *options,
146 const char * const usagestr[]);
147
7e7bbcb4
PH
148extern int parse_options_end(struct parse_opt_ctx_t *ctx);
149
150
0ce865b1
PH
151/*----- some often used options -----*/
152extern int parse_opt_abbrev_cb(const struct option *, const char *, int);
1f4a711a 153extern int parse_opt_approxidate_cb(const struct option *, const char *, int);
7f87aff2 154extern int parse_opt_verbosity_cb(const struct option *, const char *, int);
269defdf 155extern int parse_opt_with_commit(const struct option *, const char *, int);
0ce865b1
PH
156
157#define OPT__VERBOSE(var) OPT_BOOLEAN('v', "verbose", (var), "be verbose")
158#define OPT__QUIET(var) OPT_BOOLEAN('q', "quiet", (var), "be quiet")
7f87aff2
TA
159#define OPT__VERBOSITY(var) \
160 { OPTION_CALLBACK, 'v', "verbose", (var), NULL, "be more verbose", \
161 PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }, \
162 { OPTION_CALLBACK, 'q', "quiet", (var), NULL, "be more quiet", \
163 PARSE_OPT_NOARG, &parse_opt_verbosity_cb, 0 }
0ce865b1
PH
164#define OPT__DRY_RUN(var) OPT_BOOLEAN('n', "dry-run", (var), "dry run")
165#define OPT__ABBREV(var) \
166 { OPTION_CALLBACK, 0, "abbrev", (var), "n", \
167 "use <n> digits to display SHA-1s", \
168 PARSE_OPT_OPTARG, &parse_opt_abbrev_cb, 0 }
169
dbd0f5c7
JH
170extern const char *parse_options_fix_filename(const char *prefix, const char *file);
171
4a59fd13 172#endif