2 * Copyright (C) 2021 Simon Marchi <simon.marchi@efficios.com>
4 * SPDX-License-Identifier: GPL-2.0-only
8 #ifndef COMMON_ARGPAR_UTILS_H
9 #define COMMON_ARGPAR_UTILS_H
13 #include <common/macros.h>
14 #include <common/argpar/argpar.h>
15 #include <common/string-utils/format.h>
17 #define WHILE_PARSING_ARG_N_ARG_FMT "While parsing argument #%d (`%s`): "
19 enum parse_next_item_status
21 PARSE_NEXT_ITEM_STATUS_OK
= 0,
22 PARSE_NEXT_ITEM_STATUS_END
= 1,
23 PARSE_NEXT_ITEM_STATUS_ERROR
= -1,
24 PARSE_NEXT_ITEM_STATUS_ERROR_MEMORY
= -2,
28 * Parse the next argpar item using `iter`.
30 * The item in `*item` is always freed and cleared on entry.
32 * If an item is parsed successfully, return the new item in `*item` and return
33 * PARSE_NEXT_ITEM_STATUS_OK.
35 * If the end of the argument list is reached, return
36 * PARSE_NEXT_ITEM_STATUS_END.
38 * On error, print a descriptive error message and return
39 * PARSE_NEXT_ITEM_STATUS_ERROR. If `context_fmt` is non-NULL, it is formatted
40 * using the following arguments and prepended to the error message.
41 * Add `argc_offset` to the argument index mentioned in the error message.
43 * If `unknown_opt_is_error` is true, an unknown option is considered an error.
44 * Otherwise, it is considered as the end of the argument list.
46 * If `error_out` is given and PARSE_NEXT_ITEM_STATUS_ERROR is returned, set
47 * `*error_out` to the argpar_error object corresponding to the error. The
48 * caller must free the object with `argpar_error_destroy`.
51 enum parse_next_item_status
parse_next_item(struct argpar_iter
*iter
,
52 const struct argpar_item
**item
, int argc_offset
,
53 const char **argv
, bool unknown_opt_is_error
,
54 const struct argpar_error
**error_out
,
55 const char *context_fmt
, ...);