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(const struct argpar_item
*item
);
197 Returns the argument of the option parsing item \p item, or
201 Option parsing item of which to get the argument.
204 Argument of \p item, or \c NULL if none.
207 \p item is not \c NULL.
209 \p item has the type #ARGPAR_ITEM_TYPE_OPT.
211 /// @cond hidden_macro
214 const char *argpar_item_opt_arg(const struct argpar_item
*item
);
218 Returns the complete original argument, pointing to one of the
219 entries of the original arguments (in \p argv, as passed to
220 argpar_iter_create()), of the non-option parsing item \p item.
223 Non-option parsing item of which to get the complete original
227 Complete original argument of \p item.
230 \p item is not \c NULL.
232 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
234 /// @cond hidden_macro
237 const char *argpar_item_non_opt_arg(const struct argpar_item
*item
);
241 Returns the index, within \em all the original arguments (in
242 \p argv, as passed to argpar_iter_create()), of the non-option
243 parsing item \p item.
245 For example, with the following command line (all options have no
249 -f -m meow --jus mix --kilo
252 The original argument index of \c meow is 2 while the original
253 argument index of \c mix is 4.
256 Non-option parsing item of which to get the original argument index.
259 Original argument index of \p item.
262 \p item is not \c NULL.
264 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
267 argpar_item_non_opt_non_opt_index() -- Returns the non-option index
268 of a non-option parsing item.
270 /// @cond hidden_macro
273 unsigned int argpar_item_non_opt_orig_index(const struct argpar_item
*item
);
277 Returns the index, within the parsed non-option parsing items, of
278 the non-option parsing item \p item.
280 For example, with the following command line (all options have no
284 -f -m meow --jus mix --kilo
287 The non-option index of \c meow is 0 while the original
288 argument index of \c mix is 1.
291 Non-option parsing item of which to get the non-option index.
294 Non-option index of \p item.
297 \p item is not \c NULL.
299 \p item has the type #ARGPAR_ITEM_TYPE_NON_OPT.
302 argpar_item_non_opt_orig_index() -- Returns the original argument
303 index of a non-option parsing item.
305 /// @cond hidden_macro
308 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item
*item
);
312 Destroys the parsing item \p item.
315 Parsing item to destroy (may be \c NULL).
317 /// @cond hidden_macro
320 void argpar_item_destroy(const struct argpar_item
*item
);
323 @def ARGPAR_ITEM_DESTROY_AND_RESET(_item)
326 Calls argpar_item_destroy() with \p _item, and then sets \p _item
330 Item to destroy and variable to reset
331 (<code>const struct argpar_item *</code> type).
333 #define ARGPAR_ITEM_DESTROY_AND_RESET(_item) \
335 argpar_item_destroy(_item); \
348 Parsing error type, as returned by
349 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink.
351 enum argpar_error_type
{
352 /// Unknown option error
353 ARGPAR_ERROR_TYPE_UNKNOWN_OPT
,
355 /// Missing option argument error
356 ARGPAR_ERROR_TYPE_MISSING_OPT_ARG
,
358 /// Unexpected option argument error
359 ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG
,
366 Opaque parsing error type
372 Returns the type of the parsing error object \p error.
375 Parsing error of which to get the type.
381 \p error is not \c NULL.
383 /// @cond hidden_macro
386 enum argpar_error_type
argpar_error_type(const struct argpar_error
*error
);
390 Returns the index of the original argument (in \p argv, as passed to
391 argpar_iter_create()) for which the parsing error described by
395 Parsing error of which to get the original argument index.
398 Original argument index of \p error.
401 \p error is not \c NULL.
403 /// @cond hidden_macro
406 unsigned int argpar_error_orig_index(const struct argpar_error
*error
);
410 Returns the name of the unknown option for which the parsing error
411 described by \p error occurred.
413 The returned name includes any <code>-</code> or <code>\--</code>
416 With the long option with argument form, for example
417 <code>\--mireille=deyglun</code>, this function only returns the name
418 part (<code>\--mireille</code> in the last example).
421 Parsing error of which to get the name of the unknown option.
424 Name of the unknown option of \p error.
427 \p error is not \c NULL.
429 The type of \p error, as returned by
430 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
431 is #ARGPAR_ERROR_TYPE_UNKNOWN_OPT.
433 /// @cond hidden_macro
436 const char *argpar_error_unknown_opt_name(const struct argpar_error
*error
);
440 Returns the descriptor of the option for which the parsing error
441 described by \p error occurred.
444 Parsing error of which to get the option descriptor.
447 If not \c NULL, this function sets \p *is_short to:
449 - \c true if the option for which \p error occurred is a short
452 - \c false if the option for which \p error occurred is a long
457 Descriptor of the option of \p error.
460 \p error is not \c NULL.
462 The type of \p error, as returned by
463 \link argpar_error_type(const struct argpar_error *) argpar_error_type()\endlink,
464 is #ARGPAR_ERROR_TYPE_MISSING_OPT_ARG or
465 #ARGPAR_ERROR_TYPE_UNEXPECTED_OPT_ARG.
467 /// @cond hidden_macro
470 const struct argpar_opt_descr
*argpar_error_opt_descr(const struct argpar_error
*error
,
475 Destroys the parsing error \p error.
478 Parsing error to destroy (may be \c NULL).
480 /// @cond hidden_macro
483 void argpar_error_destroy(const struct argpar_error
*error
);
496 argpar_iter_create() accepts an array of instances of such a type,
497 terminated with #ARGPAR_OPT_DESCR_SENTINEL, as its \p descrs parameter.
499 The typical usage is, for example:
502 const struct argpar_opt_descr descrs[] = {
503 { 0, 'd', NULL, false },
504 { 1, '\0', "squeeze", true },
505 { 2, 'm', "meow", true },
506 ARGPAR_OPT_DESCR_SENTINEL,
510 struct argpar_opt_descr
{
511 /// Numeric ID, to uniquely identify this descriptor
514 /// Short option character, or <code>'\0'</code>
515 const char short_name
;
517 /// Long option name (without the <code>\--</code> prefix), or \c NULL
518 const char *const long_name
;
520 /// \c true if this option has an argument
526 Sentinel for an option descriptor array
528 The typical usage is, for example:
531 const struct argpar_opt_descr descrs[] = {
532 { 0, 'd', NULL, false },
533 { 1, '\0', "squeeze", true },
534 { 2, 'm', "meow", true },
535 ARGPAR_OPT_DESCR_SENTINEL,
539 #define ARGPAR_OPT_DESCR_SENTINEL \
541 -1, '\0', NULL, false \
548 Opaque argpar iterator type
550 argpar_iter_create() returns a pointer to such a type.
556 Creates and returns an argument parsing iterator to parse the
557 original arguments \p argv of which the count is \p argc using the
558 option descriptors \p descrs.
560 This function initializes the returned structure, but doesn't actually
561 start parsing the arguments.
563 argpar considers \em all the elements of \p argv, including the first
564 one, so that you would typically pass <code>(argc - 1)</code> as \p argc
565 and <code>\&argv[1]</code> as \p argv from what <code>main()</code>
566 receives, or ignore the parsing item of the first call to
569 \p *argv and \p *descrs must \em not change for all of:
571 - The lifetime of the returned iterator (until you call
572 argpar_iter_destroy()).
574 - The lifetime of any parsing item (until you call
575 argpar_item_destroy()) which argpar_iter_next() creates from the
578 - The lifetime of any parsing error (until you call
579 argpar_error_destroy()) which argpar_iter_next() creates from the
583 Number of original arguments to parse in \p argv.
585 Original arguments to parse, of which the count is \p argc.
588 Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL.
590 May contain duplicate entries.
594 New argument parsing iterator, or \c NULL on memory error.
597 \p argc is greater than 0.
599 \p argv is not \c NULL.
601 The first \p argc elements of \p argv are not \c NULL.
603 \p descrs is not \c NULL.
606 argpar_iter_destroy() -- Destroys an argument parsing iterator.
608 /// @cond hidden_macro
611 struct argpar_iter
*argpar_iter_create(unsigned int argc
,
612 const char *const *argv
,
613 const struct argpar_opt_descr
*descrs
);
617 Destroys the argument parsing iterator \p iter.
620 Argument parsing iterator to destroy (may be \c NULL).
623 argpar_iter_create() -- Creates an argument parsing iterator.
625 /// @cond hidden_macro
628 void argpar_iter_destroy(struct argpar_iter
*iter
);
632 Return type of argpar_iter_next().
634 Error status enumerators have a negative value.
636 enum argpar_iter_next_status
{
638 ARGPAR_ITER_NEXT_STATUS_OK
,
640 /// End of iteration (no more original arguments to parse)
641 ARGPAR_ITER_NEXT_STATUS_END
,
644 ARGPAR_ITER_NEXT_STATUS_ERROR
= -1,
647 ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY
= -12,
652 Sets \p *item to the next item of the argument parsing iterator
653 \p iter and advances \p iter.
655 If there are no more original arguments to parse, this function returns
656 #ARGPAR_ITER_NEXT_STATUS_END.
659 Argument parsing iterator from which to get the next parsing item.
662 On success, \p *item is the next parsing item of \p iter.
664 Destroy \p *item with argpar_item_destroy().
668 When this function returns #ARGPAR_ITER_NEXT_STATUS_ERROR,
669 if this parameter is not \c NULL, \p *error contains details about
672 Destroy \p *error with argpar_error_destroy().
679 \p iter is not \c NULL.
681 \p item is not \c NULL.
683 /// @cond hidden_macro
686 enum argpar_iter_next_status
argpar_iter_next(struct argpar_iter
*iter
,
687 const struct argpar_item
**item
,
688 const struct argpar_error
**error
);
691 * Returns the number of ingested elements from `argv`, as passed to
692 * argpar_iter_create() to create `*iter`, that were required to produce
693 * the previously returned items.
698 Returns the number of ingested original arguments (in
699 \p argv, as passed to argpar_iter_create() to create \p iter) that
700 the parser ingested to produce the \em previous parsing items.
703 Argument parsing iterator of which to get the number of ingested
707 Number of original arguments which \p iter ingested.
710 \p iter is not \c NULL.
712 /// @cond hidden_macro
715 unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter
*iter
);
725 #endif /* ARGPAR_ARGPAR_H */