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
16 See the \ref api module.
18 @addtogroup api argpar API
21 argpar is a library which provides an iterator-based API to parse
22 command-line arguments.
24 The argpar parser supports:
28 Short options without an argument, possibly tied together:
35 Short options with arguments:
38 -b 45 -f/mein/file -xyzhello
42 Long options without an argument:
45 --five-guys --burger-king --pizza-hut --subway
49 Long options with arguments (two original arguments or a single
50 one with a <code>=</code> character):
53 --security enable --time=18.56
57 Non-option arguments (anything else, including
58 <code>-</code> and <code>\--</code>).
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.
67 Create a parsing iterator with argpar_iter_create(), then repeatedly
68 call argpar_iter_next() to access the parsing results (items), until one
71 - There are no more arguments.
73 - The argument parser encounters an error (for example, an unknown
78 argpar_iter_create() accepts duplicate option descriptors in
79 \p descrs (argpar_iter_next() produces one item for each
82 A parsing item (the result of argpar_iter_next()) has the type
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).
90 argpar_iter_next() produces the items in the same order that it parses
91 original arguments, including non-option arguments. This means, for
95 --hello --count=23 /path/to/file -ab --type file -- magie
98 argpar_iter_next() produces the following items, in this order:
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>).
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".
114 * On Windows, symbols are local unless explicitly exported; see
115 * <https://gcc.gnu.org/wiki/Visibility>.
117 #if defined(_WIN32) || defined(__CYGWIN__)
118 # define ARGPAR_HIDDEN
120 # define ARGPAR_HIDDEN __attribute__((visibility("hidden")))
123 struct argpar_opt_descr
;
132 Type of a parsing item, as returned by
133 \link argpar_item_type(const struct argpar_item *) argpar_item_type()\endlink.
135 enum argpar_item_type
{
137 ARGPAR_ITEM_TYPE_OPT
,
140 ARGPAR_ITEM_TYPE_NON_OPT
,
147 Opaque parsing item type
149 argpar_iter_next() sets a pointer to such a type.
155 Returns the type of the parsing item \p item.
158 Parsing item of which to get the type.
164 \p item is not \c NULL.
166 /// @cond hidden_macro
169 enum argpar_item_type
argpar_item_type(const struct argpar_item
*item
);
173 Returns the option descriptor of the option parsing item \p item.
176 Option parsing item of which to get the option descriptor.
179 Option descriptor of \p item.
182 \p item is not \c NULL.
184 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
186 /// @cond hidden_macro
189 const struct argpar_opt_descr
*argpar_item_opt_descr(
190 const struct argpar_item
*item
);
194 Returns the argument of the option parsing item \p item, or
198 Option parsing item of which to get the argument.
201 Argument of \p item, or \c NULL if none.
204 \p item is not \c NULL.
206 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
208 /// @cond hidden_macro
211 const char *argpar_item_opt_arg(const struct argpar_item
*item
);
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.
220 Non-option parsing item of which to get the complete original
224 Complete original argument of \p item.
227 \p item is not \c NULL.
229 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
231 /// @cond hidden_macro
234 const char *argpar_item_non_opt_arg(const struct argpar_item
*item
);
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.
242 For example, with the following command line (all options have no
246 -f -m meow --jus mix --kilo
249 The original argument index of \c meow is 2 while the original
250 argument index of \c mix is 4.
253 Non-option parsing item of which to get the original argument index.
256 Original argument index of \p item.
259 \p item is not \c NULL.
261 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
264 argpar_item_non_opt_non_opt_index() -- Returns the non-option index
265 of a non-option parsing item.
267 /// @cond hidden_macro
270 unsigned int argpar_item_non_opt_orig_index(const struct argpar_item
*item
);
274 Returns the index, within the parsed non-option parsing items, of
275 the non-option parsing item \p item.
277 For example, with the following command line (all options have no
281 -f -m meow --jus mix --kilo
284 The non-option index of \c meow is 0 while the original
285 argument index of \c mix is 1.
288 Non-option parsing item of which to get the non-option index.
291 Non-option index of \p item.
294 \p item is not \c NULL.
296 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
299 argpar_item_non_opt_orig_index() -- Returns the original argument
300 index of a non-option parsing item.
302 /// @cond hidden_macro
305 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item
*item
);
309 Destroys the parsing item \p item.
312 Parsing item to destroy (may be \c NULL).
314 /// @cond hidden_macro
317 void argpar_item_destroy(const struct argpar_item
*item
);
320 @def ARGPAR_ITEM_DESTROY_AND_RESET(_item)
323 Calls argpar_item_destroy() with \p _item, and then sets \p _item
327 Item to destroy and variable to reset
328 (<code>const struct argpar_item *</code> type).
330 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \
332 argpar_item_destroy(_item); \
345 Parsing error type, as returned by
346 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink.
348 enum argpar_error_type
{
349 /// Unknown option error
350 ARGPAR_ERROR_TYPE_UNKNOWN_OPT
,
352 /// Missing option argument error
353 ARGPAR_ERROR_TYPE_MISSING_OPT_ARG
,
355 /// Unexpected option argument error
356 ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG
,
363 Opaque parsing error type
369 Returns the type of the parsing error object \p error.
372 Parsing error of which to get the type.
378 \p error is not \c NULL.
380 /// @cond hidden_macro
383 enum argpar_error_type
argpar_error_type(const struct argpar_error
*error
);
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
392 Parsing error of which to get the original argument index.
395 Original argument index of \p error.
398 \p error is not \c NULL.
400 /// @cond hidden_macro
403 unsigned int argpar_error_orig_index(const struct argpar_error
*error
);
407 Returns the name of the unknown option for which the parsing error
408 described by \p error occurred.
410 The returned name includes any <code>-</code> or <code>\--</code>
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).
418 Parsing error of which to get the name of the unknown option.
421 Name of the unknown option of \p error.
424 \p error is not \c NULL.
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.
430 /// @cond hidden_macro
433 const char *argpar_error_unknown_opt_name(const struct argpar_error
*error
);
437 Returns the descriptor of the option for which the parsing error
438 described by \p error occurred.
441 Parsing error of which to get the option descriptor.
444 If not \c NULL, this function sets \p *is_short to:
446 - \c true if the option for which \p error occurred is a short
449 - \c false if the option for which \p error occurred is a long
454 Descriptor of the option of \p error.
457 \p error is not \c NULL.
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.
464 /// @cond hidden_macro
467 const struct argpar_opt_descr
*argpar_error_opt_descr(
468 const struct argpar_error
*error
, bool *is_short
);
472 Destroys the parsing error \p error.
475 Parsing error to destroy (may be \c NULL).
477 /// @cond hidden_macro
480 void argpar_error_destroy(const struct argpar_error
*error
);
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.
496 The typical usage is, for example:
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,
507 struct argpar_opt_descr
{
508 /// Numeric ID, to uniquely identify this descriptor
511 /// Short option character, or <code>'\0'</code>
512 const char short_name
;
514 /// Long option name (without the <code>\--</code> prefix), or \c NULL
515 const char * const long_name
;
517 /// \c true if this option has an argument
523 Sentinel for an option descriptor array
525 The typical usage is, for example:
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,
536 #define ARGPAR_OPT_DESCR_SENTINEL { -1, '\0', NULL, false }
542 Opaque argpar iterator type
544 argpar_iter_create() returns a pointer to such a type.
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.
554 This function initializes the returned structure, but doesn't actually
555 start parsing the arguments.
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
563 \p *argv and \p *descrs must \em not change for all of:
565 - The lifetime of the returned iterator (until you call
566 argpar_iter_destroy()).
568 - The lifetime of any parsing item (until you call
569 argpar_item_destroy()) which argpar_iter_next() creates from the
572 - The lifetime of any parsing error (until you call
573 argpar_error_destroy()) which argpar_iter_next() creates from the
577 Number of original arguments to parse in \p argv.
579 Original arguments to parse, of which the count is \p argc.
582 Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL.
584 May contain duplicate entries.
588 New argument parsing iterator, or \c NULL on memory error.
591 \p argc is greater than 0.
593 \p argv is not \c NULL.
595 The first \p argc elements of \p argv are not \c NULL.
597 \p descrs is not \c NULL.
600 argpar_iter_destroy() -- Destroys an argument parsing iterator.
602 /// @cond hidden_macro
605 struct argpar_iter
*argpar_iter_create(unsigned int argc
,
606 const char * const *argv
,
607 const struct argpar_opt_descr
*descrs
);
611 Destroys the argument parsing iterator \p iter.
614 Argument parsing iterator to destroy (may be \c NULL).
617 argpar_iter_create() -- Creates an argument parsing iterator.
619 /// @cond hidden_macro
622 void argpar_iter_destroy(struct argpar_iter
*iter
);
626 Return type of argpar_iter_next().
628 Error status enumerators have a negative value.
630 enum argpar_iter_next_status
{
632 ARGPAR_ITER_NEXT_STATUS_OK
,
634 /// End of iteration (no more original arguments to parse)
635 ARGPAR_ITER_NEXT_STATUS_END
,
638 ARGPAR_ITER_NEXT_STATUS_ERROR
= -1,
641 ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY
= -12,
646 Sets \p *item to the next item of the argument parsing iterator
647 \p iter and advances \p iter.
649 If there are no more original arguments to parse, this function returns
650 #ARGPAR_ITER_NEXT_STATUS_END.
653 Argument parsing iterator from which to get the next parsing item.
656 On success, \p *item is the next parsing item of \p iter.
658 Destroy \p *item with argpar_item_destroy().
662 When this function returns #ARGPAR_ITER_NEXT_STATUS_ERROR,
663 if this parameter is not \c NULL, \p *error contains details about
666 Destroy \p *error with argpar_error_destroy().
673 \p iter is not \c NULL.
675 \p item is not \c NULL.
677 /// @cond hidden_macro
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
);
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.
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.
697 Argument parsing iterator of which to get the number of ingested
701 Number of original arguments which \p iter ingested.
704 \p iter is not \c NULL.
706 /// @cond hidden_macro
709 unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter
*iter
);
715 #endif /* ARGPAR_ARGPAR_H */