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