-/*
- * Parses the arguments `argv` of which the count is `argc` using the
- * sentinel-terminated (use `ARGPAR_OPT_DESCR_SENTINEL`) option
- * descriptor array `descrs`.
- *
- * This function considers ALL the elements of `argv`, including the
- * first one, so that you would typically pass `argc - 1` and
- * `&argv[1]` from what main() receives.
- *
- * This argument parser supports:
- *
- * * Short options without an argument, possibly tied together:
- *
- * -f -auf -n
- *
- * * Short options with argument:
- *
- * -b 45 -f/mein/file -xyzhello
- *
- * * Long options without an argument:
- *
- * --five-guys --burger-king --pizza-hut --subway
- *
- * * Long options with arguments:
- *
- * --security enable --time=18.56
- *
- * * Non-option arguments (anything else).
- *
- * This function does not accept `-` or `--` as arguments. The latter
- * means "end of options" for many command-line tools, but this function
- * is all about keeping the order of the arguments, so it does not mean
- * much to put them at the end. This has the side effect that a
- * non-option argument cannot have the form of an option, for example if
- * you need to pass the exact relative path `--component`. In that case,
- * you would need to pass `./--component`. There's no generic way to
- * escape `-` for the moment.
- *
- * This function accepts duplicate options (the resulting array of items
- * contains one entry for each instance).
- *
- * On success, this function returns an array of items
- * (`struct argpar_item *`). Each item is to be casted to the
- * appropriate type (`struct argpar_item_opt *` or
- * `struct argpar_item_non_opt *`) depending on its type.
- *
- * The returned array contains the items in the same order that the
- * arguments were parsed, including non-option arguments. This means,
- * for example, that for
- *
- * --hello --meow=23 /path/to/file -b
- *
- * the function returns an array of four items: two options, one
- * non-option, and one option.
- *
- * In the returned structure, `ingested_orig_args` is the number of
- * ingested arguments within `argv` to produce the resulting array of
- * items. If `fail_on_unknown_opt` is true, then on success
- * `ingested_orig_args` is equal to `argc`. Otherwise,
- * `ingested_orig_args` contains the number of original arguments until
- * an unknown _option_ occurs. For example, with
- *
- * --great --white contact nuance --shark nuclear
- *
- * if `--shark` is not described within `descrs` and
- * `fail_on_unknown_opt` is false, then `ingested_orig_args` is 4 (two
- * options, two non-options), whereas `argc` is 6.
- *
- * This makes it possible to know where a command name is, for example.
- * With those arguments:
- *
- * --verbose --stuff=23 do-something --specific-opt -f -b
- *
- * and the descriptors for `--verbose` and `--stuff` only, the function
- * returns the `--verbose` and `--stuff` option items, the
- * `do-something` non-option item, and that three original arguments
- * were ingested. This means you can start the next argument parsing
- * stage, with option descriptors depending on the command name, at
- * `&argv[3]`.
- *
- * Note that `ingested_orig_args` is not always equal to the number of
- * returned items, as
- *
- * --hello -fdw
- *
- * for example contains two ingested original arguments, but four
- * resulting items.
- *
- * On failure, the returned structure's `items` member is `NULL`, and
- * the `error` string member contains details about the error.
- *
- * You can finalize the returned structure with
- * argpar_parse_ret_fini().
- */
-ARGPAR_HIDDEN
-struct argpar_parse_ret argpar_parse(unsigned int argc,
- const char * const *argv,
- const struct argpar_opt_descr *descrs,
- bool fail_on_unknown_opt);
+/*!
+@struct argpar_iter
+
+@brief
+ Opaque argpar iterator type
+
+argpar_iter_create() returns a pointer to such a type.
+*/
+typedef struct argpar_iter argpar_iter_t;
+
+/*!
+@brief
+ Creates and returns an argument parsing iterator to parse the
+ original arguments \p argv of which the count is \p argc using the
+ option descriptors \p descrs.
+
+This function initializes the returned structure, but doesn't actually
+start parsing the arguments.
+
+argpar considers \em all the elements of \p argv, including the first
+one, so that you would typically pass <code>(argc - 1)</code> as \p argc
+and <code>\&argv[1]</code> as \p argv from what <code>main()</code>
+receives, or ignore the parsing item of the first call to
+argpar_iter_next().
+
+\p *argv and \p *descrs must \em not change for all of:
+
+- The lifetime of the returned iterator (until you call
+ argpar_iter_destroy()).
+
+- The lifetime of any parsing item (until you call
+ argpar_item_destroy()) which argpar_iter_next() creates from the
+ returned iterator.
+
+- The lifetime of any parsing error (until you call
+ argpar_error_destroy()) which argpar_iter_next() creates from the
+ returned iterator.
+
+@param[in] argc
+ Number of original arguments to parse in \p argv.
+@param[in] argv
+ Original arguments to parse, of which the count is \p argc.
+@param[in] descrs
+ @parblock
+ Option descriptor array, terminated with #ARGPAR_OPT_DESCR_SENTINEL.
+
+ May contain duplicate entries.
+ @endparblock
+
+@returns
+ New argument parsing iterator, or \c NULL on memory error.
+
+@pre
+ \p argc is greater than 0.
+@pre
+ \p argv is not \c NULL.
+@pre
+ The first \p argc elements of \p argv are not \c NULL.
+@pre
+ \p descrs is not \c NULL.
+
+@sa
+ argpar_iter_destroy() -- Destroys an argument parsing iterator.
+*/
+argpar_iter_t *argpar_iter_create(unsigned int argc, const char * const *argv,
+ const argpar_opt_descr_t *descrs) ARGPAR_NOEXCEPT;
+
+/*!
+@brief
+ Destroys the argument parsing iterator \p iter.
+
+@param[in] iter
+ Argument parsing iterator to destroy (may be \c NULL).
+
+@sa
+ argpar_iter_create() -- Creates an argument parsing iterator.
+*/
+void argpar_iter_destroy(argpar_iter_t *iter) ARGPAR_NOEXCEPT;
+
+/*!
+@brief
+ Return type of argpar_iter_next().
+
+Error status enumerators have a negative value.
+*/
+typedef enum argpar_iter_next_status
+{
+ /// Success
+ ARGPAR_ITER_NEXT_STATUS_OK,
+
+ /// End of iteration (no more original arguments to parse)
+ ARGPAR_ITER_NEXT_STATUS_END,
+
+ /// Parsing error
+ ARGPAR_ITER_NEXT_STATUS_ERROR = -1,
+
+ /// Memory error
+ ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY = -12,
+} argpar_iter_next_status_t;
+
+/*!
+@brief
+ Sets \p *item to the next item of the argument parsing iterator
+ \p iter and advances \p iter.
+
+If there are no more original arguments to parse, this function returns
+#ARGPAR_ITER_NEXT_STATUS_END.
+
+@param[in] iter
+ Argument parsing iterator from which to get the next parsing item.
+@param[out] item
+ @parblock
+ On success, \p *item is the next parsing item of \p iter.
+
+ Destroy \p *item with argpar_item_destroy().
+ @endparblock
+@param[out] error
+ @parblock
+ When this function returns #ARGPAR_ITER_NEXT_STATUS_ERROR,
+ if this parameter is not \c NULL, \p *error contains details about
+ the error.
+
+ Destroy \p *error with argpar_error_destroy().
+ @endparblock
+
+@returns
+ Status code.
+
+@pre
+ \p iter is not \c NULL.
+@pre
+ \p item is not \c NULL.
+*/
+argpar_iter_next_status_t argpar_iter_next(argpar_iter_t *iter, const argpar_item_t **item,
+ const argpar_error_t **error) ARGPAR_NOEXCEPT;