2 * SPDX-License-Identifier: MIT
4 * Copyright (c) 2019-2021 Philippe Proulx <pproulx@efficios.com>
5 * Copyright (c) 2020-2021 Simon Marchi <simon.marchi@efficios.com>
8 #ifndef ARGPAR_ARGPAR_H
9 #define ARGPAR_ARGPAR_H
20 See the \ref api module.
22 @addtogroup api argpar API
25 argpar is a library which provides an iterator-based API to parse
26 command-line arguments.
28 The argpar parser supports:
32 Short options without an argument, possibly tied together:
39 Short options with arguments:
42 -b 45 -f/mein/file -xyzhello
46 Long options without an argument:
49 --five-guys --burger-king --pizza-hut --subway
53 Long options with arguments (two original arguments or a single
54 one with a <code>=</code> character):
57 --security enable --time=18.56
61 Non-option arguments (anything else, including
62 <code>-</code> and <code>\--</code>).
64 A non-option argument cannot have the form of an option, for example
65 if you need to pass the exact relative path
66 <code>\--component</code>. In that case, you would need to pass
67 <code>./\--component</code>. There's no generic way to escape
68 <code>-</code> as of this version.
71 Create a parsing iterator with argpar_iter_create(), then repeatedly
72 call argpar_iter_next() to access the parsing results (items), until one
75 - There are no more arguments.
77 - The argument parser encounters an error (for example, an unknown
82 argpar_iter_create() accepts duplicate option descriptors in
83 \p descrs (argpar_iter_next() produces one item for each
86 A parsing item (the result of argpar_iter_next()) has the type
89 Get the type (option or non-option) of an item with
90 \link argpar_item_type(const struct argpar_item *) argpar_item_type()\endlink.
91 Each item type has its set of dedicated functions
92 (\c argpar_item_opt_ and \c argpar_item_non_opt_ prefixes).
94 argpar_iter_next() produces the items in the same order that it parses
95 original arguments, including non-option arguments. This means, for
99 --hello --count=23 /path/to/file -ab --type file -- magie
102 argpar_iter_next() produces the following items, in this order:
104 -# Option item (<code>\--hello</code>).
105 -# Option item (<code>\--count</code> with argument <code>23</code>).
106 -# Non-option item (<code>/path/to/file</code>).
107 -# Option item (<code>-a</code>).
108 -# Option item (<code>-b</code>).
109 -# Option item (<code>\--type</code> with argument <code>file</code>).
110 -# Non-option item (<code>\--</code>).
111 -# Non-option item (<code>magie</code>).
115 * If argpar is used in some shared library, we don't want said library
116 * to export its symbols, so mark them as "hidden".
118 * On Windows, symbols are local unless explicitly exported; see
119 * <https://gcc.gnu.org/wiki/Visibility>.
121 #if defined(_WIN32) || defined(__CYGWIN__)
122 # define ARGPAR_HIDDEN
124 # define ARGPAR_HIDDEN __attribute__((visibility("hidden")))
127 struct argpar_opt_descr
;
136 Type of a parsing item, as returned by
137 \link argpar_item_type(const struct argpar_item *) argpar_item_type()\endlink.
139 enum argpar_item_type
{
141 ARGPAR_ITEM_TYPE_OPT
,
144 ARGPAR_ITEM_TYPE_NON_OPT
,
151 Opaque parsing item type
153 argpar_iter_next() sets a pointer to such a type.
159 Returns the type of the parsing item \p item.
162 Parsing item of which to get the type.
168 \p item is not \c NULL.
170 /// @cond hidden_macro
173 enum argpar_item_type
argpar_item_type(const struct argpar_item
*item
);
177 Returns the option descriptor of the option parsing item \p item.
180 Option parsing item of which to get the option descriptor.
183 Option descriptor of \p item.
186 \p item is not \c NULL.
188 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
190 /// @cond hidden_macro
193 const struct argpar_opt_descr
*argpar_item_opt_descr(
194 const struct argpar_item
*item
);
198 Returns the argument of the option parsing item \p item, or
202 Option parsing item of which to get the argument.
205 Argument of \p item, or \c NULL if none.
208 \p item is not \c NULL.
210 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
212 /// @cond hidden_macro
215 const char *argpar_item_opt_arg(const struct argpar_item
*item
);
219 Returns the complete original argument, pointing to one of the
220 entries of the original arguments (in \p argv, as passed to
221 argpar_iter_create()), of the non-option parsing item \p item.
224 Non-option parsing item of which to get the complete original
228 Complete original argument of \p item.
231 \p item is not \c NULL.
233 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
235 /// @cond hidden_macro
238 const char *argpar_item_non_opt_arg(const struct argpar_item
*item
);
242 Returns the index, within \em all the original arguments (in
243 \p argv, as passed to argpar_iter_create()), of the non-option
244 parsing item \p item.
246 For example, with the following command line (all options have no
250 -f -m meow --jus mix --kilo
253 The original argument index of \c meow is 2 while the original
254 argument index of \c mix is 4.
257 Non-option parsing item of which to get the original argument index.
260 Original argument index of \p item.
263 \p item is not \c NULL.
265 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
268 argpar_item_non_opt_non_opt_index() -- Returns the non-option index
269 of a non-option parsing item.
271 /// @cond hidden_macro
274 unsigned int argpar_item_non_opt_orig_index(const struct argpar_item
*item
);
278 Returns the index, within the parsed non-option parsing items, of
279 the non-option parsing item \p item.
281 For example, with the following command line (all options have no
285 -f -m meow --jus mix --kilo
288 The non-option index of \c meow is 0 while the original
289 argument index of \c mix is 1.
292 Non-option parsing item of which to get the non-option index.
295 Non-option index of \p item.
298 \p item is not \c NULL.
300 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
303 argpar_item_non_opt_orig_index() -- Returns the original argument
304 index of a non-option parsing item.
306 /// @cond hidden_macro
309 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item
*item
);
313 Destroys the parsing item \p item.
316 Parsing item to destroy (may be \c NULL).
318 /// @cond hidden_macro
321 void argpar_item_destroy(const struct argpar_item
*item
);
324 @def ARGPAR_ITEM_DESTROY_AND_RESET(_item)
327 Calls argpar_item_destroy() with \p _item, and then sets \p _item
331 Item to destroy and variable to reset
332 (<code>const struct argpar_item *</code> type).
334 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \
336 argpar_item_destroy(_item); \
349 Parsing error type, as returned by
350 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink.
352 enum argpar_error_type
{
353 /// Unknown option error
354 ARGPAR_ERROR_TYPE_UNKNOWN_OPT
,
356 /// Missing option argument error
357 ARGPAR_ERROR_TYPE_MISSING_OPT_ARG
,
359 /// Unexpected option argument error
360 ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG
,
367 Opaque parsing error type
373 Returns the type of the parsing error object \p error.
376 Parsing error of which to get the type.
382 \p error is not \c NULL.
384 /// @cond hidden_macro
387 enum argpar_error_type
argpar_error_type(const struct argpar_error
*error
);
391 Returns the index of the original argument (in \p argv, as passed to
392 argpar_iter_create()) for which the parsing error described by
396 Parsing error of which to get the original argument index.
399 Original argument index of \p error.
402 \p error is not \c NULL.
404 /// @cond hidden_macro
407 unsigned int argpar_error_orig_index(const struct argpar_error
*error
);
411 Returns the name of the unknown option for which the parsing error
412 described by \p error occurred.
414 The returned name includes any <code>-</code> or <code>\--</code>
417 With the long option with argument form, for example
418 <code>\--mireille=deyglun</code>, this function only returns the name
419 part (<code>\--mireille</code> in the last example).
422 Parsing error of which to get the name of the unknown option.
425 Name of the unknown option of \p error.
428 \p error is not \c NULL.
430 The type of \p error, as returned by
431 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
432 is #ARGPAR_ERROR_TYPE_UNKNOWN_OPT.
434 /// @cond hidden_macro
437 const char *argpar_error_unknown_opt_name(const struct argpar_error
*error
);
441 Returns the descriptor of the option for which the parsing error
442 described by \p error occurred.
445 Parsing error of which to get the option descriptor.
448 If not \c NULL, this function sets \p *is_short to:
450 - \c true if the option for which \p error occurred is a short
453 - \c false if the option for which \p error occurred is a long
458 Descriptor of the option of \p error.
461 \p error is not \c NULL.
463 The type of \p error, as returned by
464 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
465 is #ARGPAR_ERROR_TYPE_MISSING_OPT_ARG or
466 #ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG.
468 /// @cond hidden_macro
471 const struct argpar_opt_descr
*argpar_error_opt_descr(
472 const struct argpar_error
*error
, bool *is_short
);
476 Destroys the parsing error \p error.
479 Parsing error to destroy (may be \c NULL).
481 /// @cond hidden_macro
484 void argpar_error_destroy(const struct argpar_error
*error
);
497 argpar_iter_create() accepts an array of instances of such a type,
498 terminated with #ARGPAR_OPT_DESCR_SENTINEL, as its \p descrs parameter.
500 The typical usage is, for example:
503 const struct argpar_opt_descr descrs[] = {
504 { 0, 'd', NULL, false },
505 { 1, '\0', "squeeze", true },
506 { 2, 'm', "meow", true },
507 ARGPAR_OPT_DESCR_SENTINEL,
511 struct argpar_opt_descr
{
512 /// Numeric ID, to uniquely identify this descriptor
515 /// Short option character, or <code>'\0'</code>
516 const char short_name
;
518 /// Long option name (without the <code>\--</code> prefix), or \c NULL
519 const char * const long_name
;
521 /// \c true if this option has an argument
527 Sentinel for an option descriptor array
529 The typical usage is, for example:
532 const struct argpar_opt_descr descrs[] = {
533 { 0, 'd', NULL, false },
534 { 1, '\0', "squeeze", true },
535 { 2, 'm', "meow", true },
536 ARGPAR_OPT_DESCR_SENTINEL,
540 #define ARGPAR_OPT_DESCR_SENTINEL { -1, '\0', NULL, false }
546 Opaque argpar iterator type
548 argpar_iter_create() returns a pointer to such a type.
554 Creates and returns an argument parsing iterator to parse the
555 original arguments \p argv of which the count is \p argc using the
556 option descriptors \p descrs.
558 This function initializes the returned structure, but doesn't actually
559 start parsing the arguments.
561 argpar considers \em all the elements of \p argv, including the first
562 one, so that you would typically pass <code>(argc - 1)</code> as \p argc
563 and <code>\&argv[1]</code> as \p argv from what <code>main()</code>
564 receives, or ignore the parsing item of the first call to
567 \p *argv and \p *descrs must \em not change for all of:
569 - The lifetime of the returned iterator (until you call
570 argpar_iter_destroy()).
572 - The lifetime of any parsing item (until you call
573 argpar_item_destroy()) which argpar_iter_next() creates from the
576 - The lifetime of any parsing error (until you call
577 argpar_error_destroy()) which argpar_iter_next() creates from the
581 Number of original arguments to parse in \p argv.
583 Original arguments to parse, of which the count is \p argc.
586 Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL.
588 May contain duplicate entries.
592 New argument parsing iterator, or \c NULL on memory error.
595 \p argc is greater than 0.
597 \p argv is not \c NULL.
599 The first \p argc elements of \p argv are not \c NULL.
601 \p descrs is not \c NULL.
604 argpar_iter_destroy() -- Destroys an argument parsing iterator.
606 /// @cond hidden_macro
609 struct argpar_iter
*argpar_iter_create(unsigned int argc
,
610 const char * const *argv
,
611 const struct argpar_opt_descr
*descrs
);
615 Destroys the argument parsing iterator \p iter.
618 Argument parsing iterator to destroy (may be \c NULL).
621 argpar_iter_create() -- Creates an argument parsing iterator.
623 /// @cond hidden_macro
626 void argpar_iter_destroy(struct argpar_iter
*iter
);
630 Return type of argpar_iter_next().
632 Error status enumerators have a negative value.
634 enum argpar_iter_next_status
{
636 ARGPAR_ITER_NEXT_STATUS_OK
,
638 /// End of iteration (no more original arguments to parse)
639 ARGPAR_ITER_NEXT_STATUS_END
,
642 ARGPAR_ITER_NEXT_STATUS_ERROR
= -1,
645 ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY
= -12,
650 Sets \p *item to the next item of the argument parsing iterator
651 \p iter and advances \p iter.
653 If there are no more original arguments to parse, this function returns
654 #ARGPAR_ITER_NEXT_STATUS_END.
657 Argument parsing iterator from which to get the next parsing item.
660 On success, \p *item is the next parsing item of \p iter.
662 Destroy \p *item with argpar_item_destroy().
666 When this function returns #ARGPAR_ITER_NEXT_STATUS_ERROR,
667 if this parameter is not \c NULL, \p *error contains details about
670 Destroy \p *error with argpar_error_destroy().
677 \p iter is not \c NULL.
679 \p item is not \c NULL.
681 /// @cond hidden_macro
684 enum argpar_iter_next_status
argpar_iter_next(
685 struct argpar_iter
*iter
, const struct argpar_item
**item
,
686 const struct argpar_error
**error
);
689 * Returns the number of ingested elements from `argv`, as passed to
690 * argpar_iter_create() to create `*iter`, that were required to produce
691 * the previously returned items.
696 Returns the number of ingested original arguments (in
697 \p argv, as passed to argpar_iter_create() to create \p iter) that
698 the parser ingested to produce the \em previous parsing items.
701 Argument parsing iterator of which to get the number of ingested
705 Number of original arguments which \p iter ingested.
708 \p iter is not \c NULL.
710 /// @cond hidden_macro
713 unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter
*iter
);
723 #endif /* ARGPAR_ARGPAR_H */