Commit | Line | Data |
---|---|---|
e2fb96d8 SM |
1 | /* |
2 | * SPDX-License-Identifier: MIT | |
3 | * | |
4 | * Copyright 2019 Philippe Proulx <pproulx@efficios.com> | |
5 | */ | |
6 | ||
7 | #ifndef BABELTRACE_ARGPAR_H | |
8 | #define BABELTRACE_ARGPAR_H | |
9 | ||
10 | #include <stdbool.h> | |
11 | ||
48a40005 SM |
12 | #if defined(__cplusplus) |
13 | extern "C" { | |
14 | #endif | |
15 | ||
4624dad0 SM |
16 | /* |
17 | * argpar is a library that provides facilities for argument parsing. | |
18 | * | |
19 | * Two APIs are available: | |
20 | * | |
21 | * - The iterator-style API, where you initialize a state object with | |
22 | * `argpar_state_create`, then repeatedly call `argpar_state_parse_next` to | |
23 | * get the arguments, until (1) there are no more arguments, (2) the parser | |
24 | * encounters an error (e.g. unknown option) or (3) you get bored. This | |
25 | * API gives you more control on when to stop parsing the arguments. | |
26 | * | |
27 | * - The parse-everything-in-one-shot-API, where you call `argpar_parse`, | |
28 | * which parses the arguments until (1) there are not more arguments or | |
29 | * (2) it encounters a parser error. It returns you a list of all the | |
30 | * arguments it was able to parse, which you can consult at your leisure. | |
31 | * | |
32 | * The following describes how arguments are parsed, and applies to both APIs. | |
33 | * | |
34 | * argpar parses the arguments `argv` of which the count is `argc` using the | |
35 | * sentinel-terminated (use `ARGPAR_OPT_DESCR_SENTINEL`) option | |
36 | * descriptor array `descrs`. | |
37 | * | |
38 | * argpar considers ALL the elements of `argv`, including the* first one, so | |
39 | * that you would typically pass `argc - 1` and `&argv[1]` from what main() | |
40 | * receives. | |
41 | * | |
42 | * This argument parser supports: | |
43 | * | |
44 | * * Short options without an argument, possibly tied together: | |
45 | * | |
46 | * -f -auf -n | |
47 | * | |
48 | * * Short options with argument: | |
49 | * | |
50 | * -b 45 -f/mein/file -xyzhello | |
51 | * | |
52 | * * Long options without an argument: | |
53 | * | |
54 | * --five-guys --burger-king --pizza-hut --subway | |
55 | * | |
56 | * * Long options with arguments: | |
57 | * | |
58 | * --security enable --time=18.56 | |
59 | * | |
60 | * * Non-option arguments (anything else). | |
61 | * | |
62 | * This parser does not accept `-` or `--` as arguments. The latter | |
63 | * means "end of options" for many command-line tools, but this function | |
64 | * is all about keeping the order of the arguments, so it does not mean | |
65 | * much to put them at the end. This has the side effect that a | |
66 | * non-option argument cannot have the form of an option, for example if | |
67 | * you need to pass the exact relative path `--component`. In that case, | |
68 | * you would need to pass `./--component`. There's no generic way to | |
69 | * escape `-` for the moment. | |
70 | * | |
71 | * This parser accepts duplicate options (it will output one item for each | |
72 | * instance). | |
73 | * | |
74 | * The returned items are of the type `struct argpar_item *`. Each item | |
75 | * is to be casted to the appropriate type (`struct argpar_item_opt *` or | |
76 | * `struct argpar_item_non_opt *`) depending on its type. | |
77 | * | |
78 | * The items are returned in the same order that the arguments were parsed, | |
79 | * including non-option arguments. This means, for example, that for | |
80 | * | |
81 | * --hello --meow=23 /path/to/file -b | |
82 | * | |
83 | * found items are returned in this order: option item (--hello), option item | |
84 | * (--meow=23), non-option item (/path/to/file) and option item (-b). | |
85 | */ | |
86 | ||
e2fb96d8 SM |
87 | /* Sentinel for an option descriptor array */ |
88 | #define ARGPAR_OPT_DESCR_SENTINEL { -1, '\0', NULL, false } | |
89 | ||
90 | /* | |
91 | * ARGPAR_HIDDEN: if argpar is used in some shared library, we don't want them | |
92 | * to be exported by that library, so mark them as "hidden". | |
93 | * | |
94 | * On Windows, symbols are local unless explicitly exported, | |
95 | * see https://gcc.gnu.org/wiki/Visibility | |
96 | */ | |
97 | #if defined(_WIN32) || defined(__CYGWIN__) | |
98 | #define ARGPAR_HIDDEN | |
99 | #else | |
100 | #define ARGPAR_HIDDEN __attribute__((visibility("hidden"))) | |
101 | #endif | |
102 | ||
4624dad0 SM |
103 | /* Forward-declaration for the opaque type. */ |
104 | struct argpar_state; | |
105 | ||
e2fb96d8 SM |
106 | /* Option descriptor */ |
107 | struct argpar_opt_descr { | |
108 | /* Numeric ID for this option */ | |
109 | const int id; | |
110 | ||
111 | /* Short option character, or `\0` */ | |
112 | const char short_name; | |
113 | ||
114 | /* Long option name (without `--`), or `NULL` */ | |
115 | const char * const long_name; | |
116 | ||
117 | /* True if this option has an argument */ | |
118 | const bool with_arg; | |
119 | }; | |
120 | ||
121 | /* Item type */ | |
122 | enum argpar_item_type { | |
123 | /* Option */ | |
124 | ARGPAR_ITEM_TYPE_OPT, | |
125 | ||
126 | /* Non-option */ | |
127 | ARGPAR_ITEM_TYPE_NON_OPT, | |
128 | }; | |
129 | ||
130 | /* Base item */ | |
131 | struct argpar_item { | |
132 | enum argpar_item_type type; | |
133 | }; | |
134 | ||
135 | /* Option item */ | |
136 | struct argpar_item_opt { | |
137 | struct argpar_item base; | |
138 | ||
139 | /* Corresponding descriptor */ | |
140 | const struct argpar_opt_descr *descr; | |
141 | ||
142 | /* Argument, or `NULL` if none */ | |
143 | const char *arg; | |
144 | }; | |
145 | ||
146 | /* Non-option item */ | |
147 | struct argpar_item_non_opt { | |
148 | struct argpar_item base; | |
149 | ||
150 | /* | |
151 | * Complete argument, pointing to one of the entries of the | |
152 | * original arguments (`argv`). | |
153 | */ | |
154 | const char *arg; | |
155 | ||
156 | /* Index of this argument amongst all original arguments (`argv`) */ | |
157 | unsigned int orig_index; | |
158 | ||
159 | /* Index of this argument amongst other non-option arguments */ | |
160 | unsigned int non_opt_index; | |
161 | }; | |
162 | ||
163 | struct argpar_item_array { | |
164 | /* Array of `struct argpar_item *`, or `NULL` on error */ | |
165 | struct argpar_item **items; | |
166 | ||
167 | /* Number of used slots in `items`. */ | |
168 | unsigned int n_items; | |
169 | ||
170 | /* Number of allocated slots in `items`. */ | |
171 | unsigned int n_alloc; | |
172 | }; | |
173 | ||
174 | /* What is returned by argpar_parse() */ | |
175 | struct argpar_parse_ret { | |
176 | /* Array of `struct argpar_item *`, or `NULL` on error */ | |
177 | struct argpar_item_array *items; | |
178 | ||
179 | /* Error string, or `NULL` if none */ | |
180 | char *error; | |
181 | ||
182 | /* Number of original arguments (`argv`) ingested */ | |
183 | unsigned int ingested_orig_args; | |
184 | }; | |
185 | ||
186 | /* | |
4624dad0 SM |
187 | * Parses arguments in `argv` until the end is reached or an error is |
188 | * encountered. | |
e2fb96d8 SM |
189 | * |
190 | * On success, this function returns an array of items | |
4624dad0 SM |
191 | * (field `items` of `struct argpar_parse_ret`) corresponding to each parsed |
192 | * argument. | |
e2fb96d8 SM |
193 | * |
194 | * In the returned structure, `ingested_orig_args` is the number of | |
195 | * ingested arguments within `argv` to produce the resulting array of | |
4624dad0 SM |
196 | * items. |
197 | * | |
198 | * If `fail_on_unknown_opt` is true, then on success `ingested_orig_args` is | |
199 | * equal to `argc`. Otherwise, `ingested_orig_args` contains the number of | |
200 | * original arguments until an unknown _option_ occurs. For example, with | |
e2fb96d8 SM |
201 | * |
202 | * --great --white contact nuance --shark nuclear | |
203 | * | |
204 | * if `--shark` is not described within `descrs` and | |
205 | * `fail_on_unknown_opt` is false, then `ingested_orig_args` is 4 (two | |
206 | * options, two non-options), whereas `argc` is 6. | |
207 | * | |
208 | * This makes it possible to know where a command name is, for example. | |
209 | * With those arguments: | |
210 | * | |
211 | * --verbose --stuff=23 do-something --specific-opt -f -b | |
212 | * | |
213 | * and the descriptors for `--verbose` and `--stuff` only, the function | |
214 | * returns the `--verbose` and `--stuff` option items, the | |
215 | * `do-something` non-option item, and that three original arguments | |
216 | * were ingested. This means you can start the next argument parsing | |
217 | * stage, with option descriptors depending on the command name, at | |
218 | * `&argv[3]`. | |
219 | * | |
220 | * Note that `ingested_orig_args` is not always equal to the number of | |
221 | * returned items, as | |
222 | * | |
223 | * --hello -fdw | |
224 | * | |
225 | * for example contains two ingested original arguments, but four | |
226 | * resulting items. | |
227 | * | |
228 | * On failure, the returned structure's `items` member is `NULL`, and | |
229 | * the `error` string member contains details about the error. | |
230 | * | |
231 | * You can finalize the returned structure with | |
232 | * argpar_parse_ret_fini(). | |
233 | */ | |
234 | ARGPAR_HIDDEN | |
235 | struct argpar_parse_ret argpar_parse(unsigned int argc, | |
236 | const char * const *argv, | |
237 | const struct argpar_opt_descr *descrs, | |
238 | bool fail_on_unknown_opt); | |
239 | ||
240 | /* | |
241 | * Finalizes what is returned by argpar_parse(). | |
242 | * | |
243 | * It is safe to call argpar_parse() multiple times with the same | |
244 | * structure. | |
245 | */ | |
246 | ARGPAR_HIDDEN | |
247 | void argpar_parse_ret_fini(struct argpar_parse_ret *ret); | |
248 | ||
4624dad0 SM |
249 | /* |
250 | * Creates an instance of `struct argpar_state`. | |
251 | * | |
252 | * This sets up the argpar_state structure, but does not actually | |
253 | * start parsing the arguments. | |
254 | * | |
255 | * When you are done with it, the state must be freed with | |
256 | * `argpar_state_destroy`. | |
257 | */ | |
258 | ARGPAR_HIDDEN | |
259 | struct argpar_state *argpar_state_create( | |
260 | unsigned int argc, | |
261 | const char * const *argv, | |
262 | const struct argpar_opt_descr * const descrs); | |
263 | ||
264 | /* | |
265 | * Destroys an instance of `struct argpar_state`. | |
266 | */ | |
267 | ARGPAR_HIDDEN | |
268 | void argpar_state_destroy(struct argpar_state *state); | |
269 | ||
270 | ||
271 | enum argpar_state_parse_next_status { | |
272 | ARGPAR_STATE_PARSE_NEXT_STATUS_OK, | |
273 | ARGPAR_STATE_PARSE_NEXT_STATUS_END, | |
274 | ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT, | |
275 | ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR, | |
276 | }; | |
277 | ||
278 | /* | |
279 | * Parses and returns the next argument from `state`. | |
280 | * | |
281 | * On success, an item describing the argument is returned in `*item` and | |
282 | * ARGPAR_STATE_PARSE_NEXT_STATUS_OK is returned. The item must be freed with | |
283 | * `argpar_item_destroy`. | |
284 | * | |
285 | * If there are no more arguments to parse, ARGPAR_STATE_PARSE_NEXT_STATUS_END | |
286 | * is returned. | |
287 | * | |
288 | * On failure (status codes ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR_UNKNOWN_OPT and | |
289 | * ARGPAR_STATE_PARSE_NEXT_STATUS_ERROR), an error string is returned in `*error`. | |
290 | * This string must be freed with `free`. | |
291 | */ | |
292 | enum argpar_state_parse_next_status argpar_state_parse_next( | |
293 | struct argpar_state *state, | |
294 | struct argpar_item **item, | |
295 | char **error); | |
296 | ||
297 | /* | |
298 | * Return the number of ingested elements from argv that were required to | |
299 | * produce the previously returned items. | |
300 | */ | |
301 | ARGPAR_HIDDEN | |
302 | int argpar_state_get_ingested_orig_args(struct argpar_state *state); | |
303 | ||
304 | /* | |
305 | * Destroy an instance of `struct argpar_item`, as returned by | |
306 | * argpar_state_parse_next. | |
307 | */ | |
308 | ARGPAR_HIDDEN | |
309 | void argpar_item_destroy(struct argpar_item *item); | |
310 | ||
311 | #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \ | |
312 | { \ | |
313 | argpar_item_destroy(_item); \ | |
314 | _item = NULL; \ | |
315 | } | |
316 | ||
48a40005 SM |
317 | #if defined(__cplusplus) |
318 | } | |
319 | #endif | |
4624dad0 | 320 | |
e2fb96d8 | 321 | #endif /* BABELTRACE_ARGPAR_H */ |