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