Commit | Line | Data |
---|---|---|
903a5b8a | 1 | /* |
03e1579f | 2 | * SPDX-License-Identifier: MIT |
903a5b8a | 3 | * |
fc07e526 SM |
4 | * Copyright (c) 2019-2021 Philippe Proulx <pproulx@efficios.com> |
5 | * Copyright (c) 2020-2021 Simon Marchi <simon.marchi@efficios.com> | |
903a5b8a SM |
6 | */ |
7 | ||
fe5a18f8 PP |
8 | #ifndef ARGPAR_ARGPAR_H |
9 | #define ARGPAR_ARGPAR_H | |
03e1579f | 10 | |
903a5b8a SM |
11 | #include <stdbool.h> |
12 | ||
9e2c879b PP |
13 | /*! |
14 | @mainpage | |
fc07e526 | 15 | |
9e2c879b PP |
16 | See the \ref api module. |
17 | ||
18 | @addtogroup api argpar API | |
19 | @{ | |
20 | ||
21 | argpar is a library which provides an iterator-based API to parse | |
22 | command-line arguments. | |
23 | ||
24 | The argpar parser supports: | |
25 | ||
26 | <ul> | |
27 | <li> | |
28 | Short options without an argument, possibly tied together: | |
29 | ||
30 | @code{.unparsed} | |
31 | -f -auf -n | |
32 | @endcode | |
33 | ||
34 | <li> | |
35 | Short options with arguments: | |
36 | ||
37 | @code{.unparsed} | |
38 | -b 45 -f/mein/file -xyzhello | |
39 | @endcode | |
40 | ||
41 | <li> | |
42 | Long options without an argument: | |
43 | ||
44 | @code{.unparsed} | |
45 | --five-guys --burger-king --pizza-hut --subway | |
46 | @endcode | |
47 | ||
48 | <li> | |
49 | Long options with arguments (two original arguments or a single | |
50 | one with a <code>=</code> character): | |
51 | ||
52 | @code{.unparsed} | |
53 | --security enable --time=18.56 | |
54 | @endcode | |
55 | ||
56 | <li> | |
57 | Non-option arguments (anything else, including | |
58 | <code>-</code> and <code>\--</code>). | |
59 | ||
60 | A non-option argument cannot have the form of an option, for example | |
61 | if you need to pass the exact relative path | |
62 | <code>\--component</code>. In that case, you would need to pass | |
63 | <code>./\--component</code>. There's no generic way to escape | |
64 | <code>-</code> as of this version. | |
65 | </ul> | |
66 | ||
67 | Create a parsing iterator with argpar_iter_create(), then repeatedly | |
68 | call argpar_iter_next() to access the parsing results (items), until one | |
69 | of: | |
70 | ||
71 | - There are no more arguments. | |
72 | ||
73 | - The argument parser encounters an error (for example, an unknown | |
74 | option). | |
75 | ||
76 | - You need to stop. | |
77 | ||
78 | argpar_iter_create() accepts duplicate option descriptors in | |
79 | \p descrs (argpar_iter_next() produces one item for each | |
80 | instance). | |
81 | ||
82 | A parsing item (the result of argpar_iter_next()) has the type | |
83 | #argpar_item. | |
84 | ||
85 | Get the type (option or non-option) of an item with | |
86 | argpar_item_type(). Each item type has its set of dedicated functions | |
87 | (\c argpar_item_opt_ and \c argpar_item_non_opt_ prefixes). | |
88 | ||
89 | argpar_iter_next() produces the items in the same order that it parses | |
90 | original arguments, including non-option arguments. This means, for | |
91 | example, that for: | |
92 | ||
93 | @code{.unparsed} | |
94 | --hello --count=23 /path/to/file -ab --type file -- magie | |
95 | @endcode | |
96 | ||
97 | argpar_iter_next() produces the following items, in this order: | |
98 | ||
99 | -# Option item (<code>\--hello</code>). | |
100 | -# Option item (<code>\--count</code> with argument <code>23</code>). | |
101 | -# Non-option item (<code>/path/to/file</code>). | |
102 | -# Option item (<code>-a</code>). | |
103 | -# Option item (<code>-b</code>). | |
104 | -# Option item (<code>\--type</code> with argument <code>file</code>). | |
105 | -# Non-option item (<code>\--</code>). | |
106 | -# Non-option item (<code>magie</code>). | |
107 | */ | |
903a5b8a | 108 | |
7ac57709 | 109 | /* |
fb12ac67 PP |
110 | * If argpar is used in some shared library, we don't want said library |
111 | * to export its symbols, so mark them as "hidden". | |
7ac57709 | 112 | * |
fc07e526 SM |
113 | * On Windows, symbols are local unless explicitly exported; see |
114 | * <https://gcc.gnu.org/wiki/Visibility>. | |
7ac57709 SM |
115 | */ |
116 | #if defined(_WIN32) || defined(__CYGWIN__) | |
fb12ac67 | 117 | # define ARGPAR_HIDDEN |
7ac57709 | 118 | #else |
fb12ac67 | 119 | # define ARGPAR_HIDDEN __attribute__((visibility("hidden"))) |
7ac57709 SM |
120 | #endif |
121 | ||
9e2c879b | 122 | struct argpar_opt_descr; |
903a5b8a | 123 | |
9e2c879b PP |
124 | /*! |
125 | @name Item API | |
126 | @{ | |
127 | */ | |
903a5b8a | 128 | |
9e2c879b PP |
129 | /*! |
130 | @brief | |
131 | Type of a parsing item, as returned by argpar_item_type(). | |
132 | */ | |
1c9a6bde | 133 | enum argpar_item_type { |
9e2c879b | 134 | /// Option |
1c9a6bde | 135 | ARGPAR_ITEM_TYPE_OPT, |
903a5b8a | 136 | |
9e2c879b | 137 | /// Non-option |
1c9a6bde | 138 | ARGPAR_ITEM_TYPE_NON_OPT, |
903a5b8a SM |
139 | }; |
140 | ||
9e2c879b PP |
141 | /*! |
142 | @struct argpar_item | |
143 | ||
144 | @brief | |
145 | Opaque parsing item type | |
146 | ||
147 | argpar_iter_next() sets a pointer to such a type. | |
148 | */ | |
d4539a90 | 149 | struct argpar_item; |
903a5b8a | 150 | |
9e2c879b PP |
151 | /*! |
152 | @brief | |
153 | Returns the type of the parsing item \p item. | |
154 | ||
155 | @param[in] item | |
156 | Parsing item of which to get the type. | |
157 | ||
158 | @returns | |
159 | Type of \p item. | |
160 | ||
161 | @pre | |
162 | \p item is not \c NULL. | |
163 | */ | |
164 | /// @cond hidden_macro | |
d4539a90 | 165 | ARGPAR_HIDDEN |
9e2c879b | 166 | /// @endcond |
d4539a90 | 167 | enum argpar_item_type argpar_item_type(const struct argpar_item *item); |
903a5b8a | 168 | |
9e2c879b PP |
169 | /*! |
170 | @brief | |
171 | Returns the option descriptor of the option parsing item \p item. | |
172 | ||
173 | @param[in] item | |
174 | Option parsing item of which to get the option descriptor. | |
175 | ||
176 | @returns | |
177 | Option descriptor of \p item. | |
178 | ||
179 | @pre | |
180 | \p item is not \c NULL. | |
181 | @pre | |
182 | \p item has the type #ARGPAR_ITEM_TYPE_OPT. | |
183 | */ | |
184 | /// @cond hidden_macro | |
d4539a90 | 185 | ARGPAR_HIDDEN |
9e2c879b | 186 | /// @endcond |
d4539a90 PP |
187 | const struct argpar_opt_descr *argpar_item_opt_descr( |
188 | const struct argpar_item *item); | |
903a5b8a | 189 | |
9e2c879b PP |
190 | /*! |
191 | @brief | |
192 | Returns the argument of the option parsing item \p item, or | |
193 | \c NULL if none. | |
194 | ||
195 | @param[in] item | |
196 | Option parsing item of which to get the argument. | |
197 | ||
198 | @returns | |
199 | Argument of \p item, or \c NULL if none. | |
200 | ||
201 | @pre | |
202 | \p item is not \c NULL. | |
203 | @pre | |
204 | \p item has the type #ARGPAR_ITEM_TYPE_OPT. | |
205 | */ | |
206 | /// @cond hidden_macro | |
d4539a90 | 207 | ARGPAR_HIDDEN |
9e2c879b | 208 | /// @endcond |
d4539a90 | 209 | const char *argpar_item_opt_arg(const struct argpar_item *item); |
903a5b8a | 210 | |
9e2c879b PP |
211 | /*! |
212 | @brief | |
213 | Returns the complete original argument, pointing to one of the | |
8b95d883 | 214 | entries of the original arguments (in \p argv, as passed to |
9e2c879b PP |
215 | argpar_iter_create()), of the non-option parsing item \p item. |
216 | ||
217 | @param[in] item | |
218 | Non-option parsing item of which to get the complete original | |
219 | argument. | |
220 | ||
221 | @returns | |
222 | Complete original argument of \p item. | |
223 | ||
224 | @pre | |
225 | \p item is not \c NULL. | |
226 | @pre | |
227 | \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT. | |
228 | */ | |
229 | /// @cond hidden_macro | |
d4539a90 | 230 | ARGPAR_HIDDEN |
9e2c879b | 231 | /// @endcond |
d4539a90 | 232 | const char *argpar_item_non_opt_arg(const struct argpar_item *item); |
903a5b8a | 233 | |
9e2c879b PP |
234 | /*! |
235 | @brief | |
8b95d883 PP |
236 | Returns the index, within \em all the original arguments (in |
237 | \p argv, as passed to argpar_iter_create()), of the non-option | |
238 | parsing item \p item. | |
9e2c879b PP |
239 | |
240 | For example, with the following command line (all options have no | |
241 | argument): | |
242 | ||
243 | @code{.unparsed} | |
244 | -f -m meow --jus mix --kilo | |
245 | @endcode | |
246 | ||
247 | The original argument index of \c meow is 2 while the original | |
248 | argument index of \c mix is 4. | |
249 | ||
250 | @param[in] item | |
251 | Non-option parsing item of which to get the original argument index. | |
252 | ||
253 | @returns | |
254 | Original argument index of \p item. | |
255 | ||
256 | @pre | |
257 | \p item is not \c NULL. | |
258 | @pre | |
259 | \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT. | |
260 | ||
261 | @sa | |
262 | argpar_item_non_opt_non_opt_index() -- Returns the non-option index | |
263 | of a non-option parsing item. | |
264 | */ | |
265 | /// @cond hidden_macro | |
d4539a90 | 266 | ARGPAR_HIDDEN |
9e2c879b | 267 | /// @endcond |
d4539a90 | 268 | unsigned int argpar_item_non_opt_orig_index(const struct argpar_item *item); |
903a5b8a | 269 | |
9e2c879b PP |
270 | /*! |
271 | @brief | |
272 | Returns the index, within the parsed non-option parsing items, of | |
273 | the non-option parsing item \p item. | |
274 | ||
275 | For example, with the following command line (all options have no | |
276 | argument): | |
277 | ||
278 | @code{.unparsed} | |
279 | -f -m meow --jus mix --kilo | |
280 | @endcode | |
281 | ||
282 | The non-option index of \c meow is 0 while the original | |
283 | argument index of \c mix is 1. | |
284 | ||
285 | @param[in] item | |
286 | Non-option parsing item of which to get the non-option index. | |
287 | ||
288 | @returns | |
289 | Non-option index of \p item. | |
290 | ||
291 | @pre | |
292 | \p item is not \c NULL. | |
293 | @pre | |
294 | \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT. | |
295 | ||
296 | @sa | |
297 | argpar_item_non_opt_orig_index() -- Returns the original argument | |
298 | index of a non-option parsing item. | |
299 | */ | |
300 | /// @cond hidden_macro | |
d4539a90 | 301 | ARGPAR_HIDDEN |
9e2c879b | 302 | /// @endcond |
d4539a90 | 303 | unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item *item); |
903a5b8a | 304 | |
9e2c879b PP |
305 | /*! |
306 | @brief | |
307 | Destroys the parsing item \p item. | |
308 | ||
309 | @param[in] item | |
310 | Parsing item to destroy (may be \c NULL). | |
311 | */ | |
312 | /// @cond hidden_macro | |
a473f6cb | 313 | ARGPAR_HIDDEN |
9e2c879b | 314 | /// @endcond |
a473f6cb PP |
315 | void argpar_item_destroy(const struct argpar_item *item); |
316 | ||
9e2c879b PP |
317 | /*! |
318 | @def ARGPAR_ITEM_DESTROY_AND_RESET(_item) | |
319 | ||
320 | @brief | |
321 | Calls argpar_item_destroy() with \p _item, and then sets \p _item | |
322 | to \c NULL. | |
323 | ||
324 | @param[in] _item | |
325 | Item to destroy and variable to reset | |
326 | (<code>const struct argpar_item *</code> type). | |
327 | */ | |
328 | #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \ | |
329 | { \ | |
330 | argpar_item_destroy(_item); \ | |
331 | _item = NULL; \ | |
332 | } | |
333 | ||
334 | /// @} | |
335 | ||
8b95d883 PP |
336 | /*! |
337 | @name Error API | |
338 | @{ | |
339 | */ | |
340 | ||
10aefab2 SM |
341 | enum argpar_error_type { |
342 | /// Unknown option error | |
343 | ARGPAR_ERROR_TYPE_UNKNOWN_OPT, | |
344 | ||
345 | /// Missing option argument error | |
346 | ARGPAR_ERROR_TYPE_MISSING_OPT_ARG, | |
347 | ||
348 | /// Unexpected option argument error | |
349 | ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG, | |
350 | }; | |
351 | ||
8b95d883 PP |
352 | /*! |
353 | @struct argpar_error | |
354 | ||
355 | @brief | |
356 | Opaque parsing error type | |
357 | */ | |
358 | struct argpar_error; | |
359 | ||
10aefab2 SM |
360 | ARGPAR_HIDDEN |
361 | enum argpar_error_type argpar_error_type( | |
362 | const struct argpar_error *error); | |
363 | ||
8b95d883 PP |
364 | /*! |
365 | @brief | |
366 | Returns the index of the original argument (in \p argv, as passed to | |
367 | argpar_iter_create()) for which the parsing error described by | |
368 | \p error occurred. | |
369 | ||
370 | @param[in] error | |
371 | Parsing error of which to get the original argument index. | |
372 | ||
373 | @returns | |
374 | Original argument index of \p error. | |
375 | ||
376 | @pre | |
377 | \p error is not \c NULL. | |
378 | */ | |
379 | /// @cond hidden_macro | |
380 | ARGPAR_HIDDEN | |
381 | /// @endcond | |
382 | unsigned int argpar_error_orig_index(const struct argpar_error *error); | |
383 | ||
384 | /*! | |
385 | @brief | |
386 | Returns the name of the unknown option for which the parsing error | |
387 | described by \p error occurred. | |
388 | ||
389 | The returned name includes any <code>-</code> or <code>\--</code> | |
390 | prefix. | |
391 | ||
392 | With the long option with argument form, for example | |
393 | <code>\--mireille=deyglun</code>, this function only returns the name | |
394 | part (<code>\--mireille</code> in the last example). | |
395 | ||
396 | You may only call this function if the call to argpar_iter_next() which | |
397 | set \p error returned #ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT. | |
398 | ||
399 | @param[in] error | |
400 | Parsing error of which to get the name of the unknown option. | |
401 | ||
402 | @returns | |
403 | Name of the unknown option of \p error. | |
404 | ||
405 | @pre | |
406 | \p error is not \c NULL. | |
407 | @pre | |
408 | The call to argpar_iter_next() which set \p error returned | |
409 | #ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT. | |
410 | */ | |
411 | /// @cond hidden_macro | |
412 | ARGPAR_HIDDEN | |
413 | /// @endcond | |
414 | const char *argpar_error_unknown_opt_name(const struct argpar_error *error); | |
415 | ||
416 | /*! | |
417 | @brief | |
418 | Returns the descriptor of the option for which the parsing error | |
419 | described by \p error occurred. | |
420 | ||
421 | You may only call this function if the call to argpar_iter_next() which | |
422 | set \p error returned #ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG or | |
423 | #ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPG_ARG. | |
424 | ||
425 | @param[in] error | |
426 | Parsing error of which to get the option descriptor. | |
427 | @param[out] is_short | |
428 | @parblock | |
429 | If not \c NULL, this function sets \p *is_short to: | |
430 | ||
431 | - \c true if the option for which \p error occurred is a short | |
432 | option. | |
433 | ||
434 | - \c false if the option for which \p error occurred is a long | |
435 | option. | |
436 | @endparblock | |
437 | ||
438 | @returns | |
439 | Descriptor of the option of \p error. | |
440 | ||
441 | @pre | |
442 | \p error is not \c NULL. | |
443 | @pre | |
444 | The call to argpar_iter_next() which set \p error returned | |
445 | #ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG or | |
446 | #ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPG_ARG. | |
447 | */ | |
448 | /// @cond hidden_macro | |
449 | ARGPAR_HIDDEN | |
450 | /// @endcond | |
451 | const struct argpar_opt_descr *argpar_error_opt_descr( | |
452 | const struct argpar_error *error, bool *is_short); | |
453 | ||
454 | /*! | |
455 | @brief | |
456 | Destroys the parsing error \p error. | |
457 | ||
458 | @param[in] error | |
459 | Parsing error to destroy (may be \c NULL). | |
460 | */ | |
461 | /// @cond hidden_macro | |
462 | ARGPAR_HIDDEN | |
463 | /// @endcond | |
464 | void argpar_error_destroy(const struct argpar_error *error); | |
465 | ||
466 | /// @} | |
467 | ||
9e2c879b PP |
468 | /*! |
469 | @name Iterator API | |
470 | @{ | |
471 | */ | |
472 | ||
473 | /*! | |
474 | @brief | |
475 | Option descriptor | |
476 | ||
477 | argpar_iter_create() accepts an array of instances of such a type, | |
478 | terminated with #ARGPAR_OPT_DESCR_SENTINEL, as its \p descrs parameter. | |
479 | ||
480 | The typical usage is, for example: | |
481 | ||
482 | @code | |
483 | const struct argpar_opt_descr descrs[] = { | |
484 | { 0, 'd', NULL, false }, | |
485 | { 1, '\0', "squeeze", true }, | |
486 | { 2, 'm', "meow", true }, | |
487 | ARGPAR_OPT_DESCR_SENTINEL, | |
488 | }; | |
489 | @endcode | |
490 | */ | |
491 | struct argpar_opt_descr { | |
492 | /// Numeric ID, to uniquely identify this descriptor | |
493 | const int id; | |
494 | ||
495 | /// Short option character, or <code>'\0'</code> | |
496 | const char short_name; | |
497 | ||
498 | /// Long option name (without the <code>\--</code> prefix), or \c NULL | |
499 | const char * const long_name; | |
500 | ||
501 | /// \c true if this option has an argument | |
502 | const bool with_arg; | |
503 | }; | |
504 | ||
505 | /*! | |
506 | @brief | |
507 | Sentinel for an option descriptor array | |
508 | ||
509 | The typical usage is, for example: | |
510 | ||
511 | @code | |
512 | const struct argpar_opt_descr descrs[] = { | |
513 | { 0, 'd', NULL, false }, | |
514 | { 1, '\0', "squeeze", true }, | |
515 | { 2, 'm', "meow", true }, | |
516 | ARGPAR_OPT_DESCR_SENTINEL, | |
517 | }; | |
518 | @endcode | |
519 | */ | |
520 | #define ARGPAR_OPT_DESCR_SENTINEL { -1, '\0', NULL, false } | |
521 | ||
522 | /*! | |
523 | @struct argpar_iter | |
524 | ||
525 | @brief | |
526 | Opaque argpar iterator type | |
527 | ||
528 | argpar_iter_create() returns a pointer to such a type. | |
529 | */ | |
530 | struct argpar_iter; | |
531 | ||
532 | /*! | |
533 | @brief | |
534 | Creates and returns an argument parsing iterator to parse the | |
535 | original arguments \p argv of which the count is \p argc using the | |
536 | option descriptors \p descrs. | |
537 | ||
538 | This function initializes the returned structure, but doesn't actually | |
539 | start parsing the arguments. | |
540 | ||
541 | argpar considers \em all the elements of \p argv, including the first | |
542 | one, so that you would typically pass <code>(argc - 1)</code> as \p argc | |
543 | and <code>\&argv[1]</code> as \p argv from what <code>main()</code> | |
544 | receives, or ignore the parsing item of the first call to | |
545 | argpar_iter_next(). | |
546 | ||
8b95d883 PP |
547 | \p *argv and \p *descrs must \em not change for all of: |
548 | ||
549 | - The lifetime of the returned iterator (until you call | |
550 | argpar_iter_destroy()). | |
551 | ||
552 | - The lifetime of any parsing item (until you call | |
553 | argpar_item_destroy()) which argpar_iter_next() creates from the | |
554 | returned iterator. | |
555 | ||
556 | - The lifetime of any parsing error (until you call | |
557 | argpar_error_destroy()) which argpar_iter_next() creates from the | |
558 | returned iterator. | |
9e2c879b PP |
559 | |
560 | @param[in] argc | |
561 | Number of original arguments to parse in \p argv. | |
562 | @param[in] argv | |
563 | Original arguments to parse, of which the count is \p argc. | |
564 | @param[in] descrs | |
565 | @parblock | |
566 | Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL. | |
567 | ||
568 | May contain duplicate entries. | |
569 | @endparblock | |
570 | ||
571 | @returns | |
572 | New argument parsing iterator, or \c NULL on memory error. | |
573 | ||
574 | @pre | |
575 | \p argc is greater than 0. | |
576 | @pre | |
577 | \p argv is not \c NULL. | |
578 | @pre | |
579 | The first \p argc elements of \p argv are not \c NULL. | |
580 | @pre | |
581 | \p descrs is not \c NULL. | |
582 | ||
583 | @sa | |
584 | argpar_iter_destroy() -- Destroys an argument parsing iterator. | |
585 | */ | |
586 | /// @cond hidden_macro | |
fc07e526 | 587 | ARGPAR_HIDDEN |
9e2c879b | 588 | /// @endcond |
fc07e526 SM |
589 | struct argpar_iter *argpar_iter_create(unsigned int argc, |
590 | const char * const *argv, | |
591 | const struct argpar_opt_descr *descrs); | |
592 | ||
9e2c879b PP |
593 | /*! |
594 | @brief | |
595 | Destroys the argument parsing iterator \p iter. | |
596 | ||
597 | @param[in] iter | |
598 | Argument parsing iterator to destroy (may be \c NULL). | |
599 | ||
600 | @sa | |
601 | argpar_iter_create() -- Creates an argument parsing iterator. | |
602 | */ | |
603 | /// @cond hidden_macro | |
fc07e526 | 604 | ARGPAR_HIDDEN |
9e2c879b | 605 | /// @endcond |
fc07e526 SM |
606 | void argpar_iter_destroy(struct argpar_iter *iter); |
607 | ||
9e2c879b PP |
608 | /*! |
609 | @brief | |
610 | Return type of argpar_iter_next(). | |
10197dcc PP |
611 | |
612 | Error status enumerators have a negative value. | |
9e2c879b | 613 | */ |
2af370d0 | 614 | enum argpar_iter_next_status { |
9e2c879b | 615 | /// Success |
2af370d0 | 616 | ARGPAR_ITER_NEXT_STATUS_OK, |
9e2c879b PP |
617 | |
618 | /// End of iteration (no more original arguments to parse) | |
2af370d0 | 619 | ARGPAR_ITER_NEXT_STATUS_END, |
9e2c879b | 620 | |
10aefab2 SM |
621 | /// Argument error |
622 | ARGPAR_ITER_NEXT_STATUS_ERROR = -1, | |
9e2c879b PP |
623 | |
624 | /// Memory error | |
10197dcc | 625 | ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY = -12, |
fc07e526 SM |
626 | }; |
627 | ||
9e2c879b PP |
628 | /*! |
629 | @brief | |
630 | Sets \p *item to the next item of the argument parsing iterator | |
631 | \p iter and advances \p iter. | |
632 | ||
633 | If there are no more original arguments to parse, this function returns | |
634 | #ARGPAR_ITER_NEXT_STATUS_END. | |
635 | ||
636 | @param[in] iter | |
637 | Argument parsing iterator from which to get the next parsing item. | |
638 | @param[out] item | |
639 | @parblock | |
640 | On success, \p *item is the next parsing item of \p iter. | |
641 | ||
642 | Destroy \p *item with argpar_item_destroy(). | |
643 | @endparblock | |
644 | @param[out] error | |
645 | @parblock | |
646 | When this function returns | |
647 | #ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT, | |
648 | #ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG, or | |
649 | #ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPG_ARG, if this parameter | |
650 | is not \c NULL, | |
8b95d883 | 651 | \p *error contains details about the error. |
9e2c879b | 652 | |
8b95d883 | 653 | Destroy \p *error with argpar_error_destroy(). |
9e2c879b PP |
654 | @endparblock |
655 | ||
656 | @returns | |
657 | Status code. | |
658 | ||
659 | @pre | |
660 | \p iter is not \c NULL. | |
661 | @pre | |
662 | \p item is not \c NULL. | |
663 | */ | |
664 | /// @cond hidden_macro | |
665 | ARGPAR_HIDDEN | |
666 | /// @endcond | |
2af370d0 | 667 | enum argpar_iter_next_status argpar_iter_next( |
fc07e526 | 668 | struct argpar_iter *iter, const struct argpar_item **item, |
8b95d883 | 669 | const struct argpar_error **error); |
fc07e526 SM |
670 | |
671 | /* | |
672 | * Returns the number of ingested elements from `argv`, as passed to | |
673 | * argpar_iter_create() to create `*iter`, that were required to produce | |
674 | * the previously returned items. | |
675 | */ | |
9e2c879b PP |
676 | |
677 | /*! | |
678 | @brief | |
679 | Returns the number of ingested original arguments (in | |
8b95d883 | 680 | \p argv, as passed to argpar_iter_create() to create \p iter) that |
9e2c879b PP |
681 | the parser ingested to produce the \em previous parsing items. |
682 | ||
683 | @param[in] iter | |
684 | Argument parsing iterator of which to get the number of ingested | |
685 | original arguments. | |
686 | ||
687 | @returns | |
688 | Number of original arguments which \p iter ingested. | |
689 | ||
690 | @pre | |
691 | \p iter is not \c NULL. | |
692 | */ | |
693 | /// @cond hidden_macro | |
fc07e526 | 694 | ARGPAR_HIDDEN |
9e2c879b | 695 | /// @endcond |
f3ab5ca1 | 696 | unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter *iter); |
fc07e526 | 697 | |
9e2c879b PP |
698 | /// @} |
699 | ||
700 | /// @} | |
fc07e526 | 701 | |
fe5a18f8 | 702 | #endif /* ARGPAR_ARGPAR_H */ |