Remove "invalid argument" statuses

[argpar.git] / argpar / argpar.h

diff --git a/argpar/argpar.h b/argpar/argpar.h
index 1fb8835f67f6df274c1f1d799f1ad2133f3f0ba0..0a7631524f47f1e2bf763a8eb3f5b3dfc87b73f2 100644 (file)
--- a/argpar/argpar.h
+++ b/argpar/argpar.h
@@ -67,10 +67,7 @@
  *
  * * Non-option arguments (anything else).
  *
- * The argpar parsers don't accept `-` or `--` as arguments. The latter
- * means "end of options" for many command-line tools, but this library
- * is all about keeping the order of the arguments, so it doesn't mean
- * much to put them at the end. This has the side effect that a
+ * The argpar parsers parse `-` and `--` as non-option arguments. 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
@@ -128,7 +125,7 @@ struct argpar_opt_descr {
        /* Short option character, or `\0` */
        const char short_name;
 
-       /* Long option name (without `--`), or `NULL` */
+       /* Long option name (without the `--` prefix), or `NULL` */
        const char * const long_name;
 
        /* True if this option has an argument */
@@ -188,6 +185,12 @@ unsigned int argpar_item_non_opt_orig_index(const struct argpar_item *item);
 ARGPAR_HIDDEN
 unsigned int argpar_item_non_opt_non_opt_index(const struct argpar_item *item);
 
+/*
+ * Destroys `item`, as created by argpar_iter_next().
+ */
+ARGPAR_HIDDEN
+void argpar_item_destroy(const struct argpar_item *item);
+
 struct argpar_item_array {
        const struct argpar_item **items;
 
@@ -284,7 +287,9 @@ void argpar_parse_ret_fini(struct argpar_parse_ret *ret);
  * actually start parsing the arguments.
  *
  * `*argv` and `*descrs` must NOT change for the lifetime of the
- * returned iterator (until you call argpar_iter_destroy()).
+ * returned iterator (until you call argpar_iter_destroy()) and for the
+ * lifetime of any parsing item (until you call argpar_item_destroy())
+ * argpar_iter_next() creates for the returned iterator.
  *
  * Call argpar_iter_next() with the returned iterator to obtain the next
  * parsing result (item).
@@ -308,7 +313,6 @@ enum argpar_iter_next_status {
        ARGPAR_ITER_NEXT_STATUS_END,
        ARGPAR_ITER_NEXT_STATUS_ERROR_UNKNOWN_OPT,
        ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG,
-       ARGPAR_ITER_NEXT_STATUS_ERROR_INVALID_ARG,
        ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG,
        ARGPAR_ITER_NEXT_STATUS_ERROR_MEMORY,
 };
@@ -339,9 +343,6 @@ enum argpar_iter_next_status {
  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_MISSING_OPT_ARG`:
  *       Missing option argument.
  *
- *   `ARGPAR_ITER_NEXT_STATUS_ERROR_INVALID_ARG`:
- *       Invalid argument.
- *
  *   `ARGPAR_ITER_NEXT_STATUS_ERROR_UNEXPECTED_OPT_ARG`:
  *       Unexpected option argument.
  *
@@ -362,13 +363,7 @@ enum argpar_iter_next_status argpar_iter_next(
  * the previously returned items.
  */
 ARGPAR_HIDDEN
-unsigned int argpar_iter_get_ingested_orig_args(const struct argpar_iter *iter);
-
-/*
- * Destroys `item`, as created by argpar_iter_next().
- */
-ARGPAR_HIDDEN
-void argpar_item_destroy(const struct argpar_item *item);
+unsigned int argpar_iter_ingested_orig_args(const struct argpar_iter *iter);
 
 /*
  * Destroys `_item` (`const struct argpar_item *`) and sets it to