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
13 #if defined(__cplusplus)
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 /* Internal: `noexcept` specifier if C++ ≥ 11 */
128 #if defined(__cplusplus) && (__cplusplus >= 201103L || (defined(_MSC_VER) && _MSC_VER >= 1900))
129 # define ARGPAR_NOEXCEPT noexcept
131 # define ARGPAR_NOEXCEPT
134 struct argpar_opt_descr
;
143 Type of a parsing item, as returned by
144 \link argpar_item_type(const struct argpar_item *) argpar_item_type()\endlink.
146 enum argpar_item_type
{
148 ARGPAR_ITEM_TYPE_OPT
,
151 ARGPAR_ITEM_TYPE_NON_OPT
,
158 Opaque parsing item type
160 argpar_iter_next() sets a pointer to such a type.
166 Returns the type of the parsing item \p item.
169 Parsing item of which to get the type.
175 \p item is not \c NULL.
177 /// @cond hidden_macro
180 enum argpar_item_type
argpar_item_type(
181 const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
185 Returns the option descriptor of the option parsing item \p item.
188 Option parsing item of which to get the option descriptor.
191 Option descriptor of \p item.
194 \p item is not \c NULL.
196 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
198 /// @cond hidden_macro
201 const struct argpar_opt_descr
*argpar_item_opt_descr(
202 const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
206 Returns the argument of the option parsing item \p item, or
210 Option parsing item of which to get the argument.
213 Argument of \p item, or \c NULL if none.
216 \p item is not \c NULL.
218 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
220 /// @cond hidden_macro
223 const char *argpar_item_opt_arg(const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
227 Returns the complete original argument, pointing to one of the
228 entries of the original arguments (in \p argv, as passed to
229 argpar_iter_create()), of the non-option parsing item \p item.
232 Non-option parsing item of which to get the complete original
236 Complete original argument of \p item.
239 \p item is not \c NULL.
241 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
243 /// @cond hidden_macro
246 const char *argpar_item_non_opt_arg(
247 const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
251 Returns the index, within \em all the original arguments (in
252 \p argv, as passed to argpar_iter_create()), of the non-option
253 parsing item \p item.
255 For example, with the following command line (all options have no
259 -f -m meow --jus mix --kilo
262 The original argument index of \c meow is 2 while the original
263 argument index of \c mix is 4.
266 Non-option parsing item of which to get the original argument index.
269 Original argument index of \p item.
272 \p item is not \c NULL.
274 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
277 argpar_item_non_opt_non_opt_index() -- Returns the non-option index
278 of a non-option parsing item.
280 /// @cond hidden_macro
283 unsigned int argpar_item_non_opt_orig_index(
284 const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
288 Returns the index, within the parsed non-option parsing items, of
289 the non-option parsing item \p item.
291 For example, with the following command line (all options have no
295 -f -m meow --jus mix --kilo
298 The non-option index of \c meow is 0 while the original
299 argument index of \c mix is 1.
302 Non-option parsing item of which to get the non-option index.
305 Non-option index of \p item.
308 \p item is not \c NULL.
310 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
313 argpar_item_non_opt_orig_index() -- Returns the original argument
314 index of a non-option parsing item.
316 /// @cond hidden_macro
319 unsigned int argpar_item_non_opt_non_opt_index(
320 const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
324 Destroys the parsing item \p item.
327 Parsing item to destroy (may be \c NULL).
329 /// @cond hidden_macro
332 void argpar_item_destroy(const struct argpar_item
*item
) ARGPAR_NOEXCEPT
;
335 @def ARGPAR_ITEM_DESTROY_AND_RESET(_item)
338 Calls argpar_item_destroy() with \p _item, and then sets \p _item
342 Item to destroy and variable to reset
343 (<code>const struct argpar_item *</code> type).
345 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \
347 argpar_item_destroy(_item); \
360 Parsing error type, as returned by
361 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink.
363 enum argpar_error_type
{
364 /// Unknown option error
365 ARGPAR_ERROR_TYPE_UNKNOWN_OPT
,
367 /// Missing option argument error
368 ARGPAR_ERROR_TYPE_MISSING_OPT_ARG
,
370 /// Unexpected option argument error
371 ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG
,
378 Opaque parsing error type
384 Returns the type of the parsing error object \p error.
387 Parsing error of which to get the type.
393 \p error is not \c NULL.
395 /// @cond hidden_macro
398 enum argpar_error_type
argpar_error_type(
399 const struct argpar_error
*error
) ARGPAR_NOEXCEPT
;
403 Returns the index of the original argument (in \p argv, as passed to
404 argpar_iter_create()) for which the parsing error described by
408 Parsing error of which to get the original argument index.
411 Original argument index of \p error.
414 \p error is not \c NULL.
416 /// @cond hidden_macro
419 unsigned int argpar_error_orig_index(
420 const struct argpar_error
*error
) ARGPAR_NOEXCEPT
;
424 Returns the name of the unknown option for which the parsing error
425 described by \p error occurred.
427 The returned name includes any <code>-</code> or <code>\--</code>
430 With the long option with argument form, for example
431 <code>\--mireille=deyglun</code>, this function only returns the name
432 part (<code>\--mireille</code> in the last example).
435 Parsing error of which to get the name of the unknown option.
438 Name of the unknown option of \p error.
441 \p error is not \c NULL.
443 The type of \p error, as returned by
444 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
445 is #ARGPAR_ERROR_TYPE_UNKNOWN_OPT.
447 /// @cond hidden_macro
450 const char *argpar_error_unknown_opt_name(
451 const struct argpar_error
*error
) ARGPAR_NOEXCEPT
;
455 Returns the descriptor of the option for which the parsing error
456 described by \p error occurred.
459 Parsing error of which to get the option descriptor.
462 If not \c NULL, this function sets \p *is_short to:
464 - \c true if the option for which \p error occurred is a short
467 - \c false if the option for which \p error occurred is a long
472 Descriptor of the option of \p error.
475 \p error is not \c NULL.
477 The type of \p error, as returned by
478 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
479 is #ARGPAR_ERROR_TYPE_MISSING_OPT_ARG or
480 #ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG.
482 /// @cond hidden_macro
485 const struct argpar_opt_descr
*argpar_error_opt_descr(
486 const struct argpar_error
*error
,
487 bool *is_short
) ARGPAR_NOEXCEPT
;
491 Destroys the parsing error \p error.
494 Parsing error to destroy (may be \c NULL).
496 /// @cond hidden_macro
499 void argpar_error_destroy(const struct argpar_error
*error
) ARGPAR_NOEXCEPT
;
512 argpar_iter_create() accepts an array of instances of such a type,
513 terminated with #ARGPAR_OPT_DESCR_SENTINEL, as its \p descrs parameter.
515 The typical usage is, for example:
518 const struct argpar_opt_descr descrs[] = {
519 { 0, 'd', NULL, false },
520 { 1, '\0', "squeeze", true },
521 { 2, 'm', "meow", true },
522 ARGPAR_OPT_DESCR_SENTINEL,
526 struct argpar_opt_descr
{
527 /// Numeric ID, to uniquely identify this descriptor
530 /// Short option character, or <code>'\0'</code>
531 const char short_name
;
533 /// Long option name (without the <code>\--</code> prefix), or \c NULL
534 const char * const long_name
;
536 /// \c true if this option has an argument
542 Sentinel for an option descriptor array
544 The typical usage is, for example:
547 const struct argpar_opt_descr descrs[] = {
548 { 0, 'd', NULL, false },
549 { 1, '\0', "squeeze", true },
550 { 2, 'm', "meow", true },
551 ARGPAR_OPT_DESCR_SENTINEL,
555 #define ARGPAR_OPT_DESCR_SENTINEL { -1, '\0', NULL, false }
561 Opaque argpar iterator type
563 argpar_iter_create() returns a pointer to such a type.
569 Creates and returns an argument parsing iterator to parse the
570 original arguments \p argv of which the count is \p argc using the
571 option descriptors \p descrs.
573 This function initializes the returned structure, but doesn't actually
574 start parsing the arguments.
576 argpar considers \em all the elements of \p argv, including the first
577 one, so that you would typically pass <code>(argc - 1)</code> as \p argc
578 and <code>\&argv[1]</code> as \p argv from what <code>main()</code>
579 receives, or ignore the parsing item of the first call to
582 \p *argv and \p *descrs must \em not change for all of:
584 - The lifetime of the returned iterator (until you call
585 argpar_iter_destroy()).
587 - The lifetime of any parsing item (until you call
588 argpar_item_destroy()) which argpar_iter_next() creates from the
591 - The lifetime of any parsing error (until you call
592 argpar_error_destroy()) which argpar_iter_next() creates from the
596 Number of original arguments to parse in \p argv.
598 Original arguments to parse, of which the count is \p argc.
601 Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL.
603 May contain duplicate entries.
607 New argument parsing iterator, or \c NULL on memory error.
610 \p argc is greater than 0.
612 \p argv is not \c NULL.
614 The first \p argc elements of \p argv are not \c NULL.
616 \p descrs is not \c NULL.
619 argpar_iter_destroy() -- Destroys an argument parsing iterator.
621 /// @cond hidden_macro
624 struct argpar_iter
*argpar_iter_create(unsigned int argc
,
625 const char * const *argv
,
626 const struct argpar_opt_descr
*descrs
) ARGPAR_NOEXCEPT
;
630 Destroys the argument parsing iterator \p iter.
633 Argument parsing iterator to destroy (may be \c NULL).
636 argpar_iter_create() -- Creates an argument parsing iterator.
638 /// @cond hidden_macro
641 void argpar_iter_destroy(struct argpar_iter
*iter
) ARGPAR_NOEXCEPT
;
645 Return type of argpar_iter_next().
647 Error status enumerators have a negative value.
649 enum argpar_iter_next_status
{
651 ARGPAR_ITER_NEXT_STATUS_OK
,
653 /// End of iteration (no more original arguments to parse)
654 ARGPAR_ITER_NEXT_STATUS_END
,
657 ARGPAR_ITER_NEXT_STATUS_ERROR
= -1,
660 ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY
= -12,
665 Sets \p *item to the next item of the argument parsing iterator
666 \p iter and advances \p iter.
668 If there are no more original arguments to parse, this function returns
669 #ARGPAR_ITER_NEXT_STATUS_END.
672 Argument parsing iterator from which to get the next parsing item.
675 On success, \p *item is the next parsing item of \p iter.
677 Destroy \p *item with argpar_item_destroy().
681 When this function returns #ARGPAR_ITER_NEXT_STATUS_ERROR,
682 if this parameter is not \c NULL, \p *error contains details about
685 Destroy \p *error with argpar_error_destroy().
692 \p iter is not \c NULL.
694 \p item is not \c NULL.
696 /// @cond hidden_macro
699 enum argpar_iter_next_status
argpar_iter_next(
700 struct argpar_iter
*iter
, const struct argpar_item
**item
,
701 const struct argpar_error
**error
) ARGPAR_NOEXCEPT
;
704 * Returns the number of ingested elements from `argv`, as passed to
705 * argpar_iter_create() to create `*iter`, that were required to produce
706 * the previously returned items.
711 Returns the number of ingested original arguments (in
712 \p argv, as passed to argpar_iter_create() to create \p iter) that
713 the parser ingested to produce the \em previous parsing items.
716 Argument parsing iterator of which to get the number of ingested
720 Number of original arguments which \p iter ingested.
723 \p iter is not \c NULL.
725 /// @cond hidden_macro
728 unsigned int argpar_iter_ingested_orig_args(
729 const struct argpar_iter
*iter
) ARGPAR_NOEXCEPT
;
735 #if defined(__cplusplus)
739 #endif /* ARGPAR_ARGPAR_H */