shared/options: add new helper option_parser_get_arg

option_parser_next_arg() is renamed to option_parser_peek_next_arg()
to match option_parser_consume_next_arg().

A new helper is added option_parser_get_arg(…, n). It is a common pattern
to only need a single arg, and getting an array and extracting a single
item from it is too verbose.

src/shared/options.c

@@ -344,7 +344,7 @@ int option_parse(
         return r;
 }
 
-char* option_parser_next_arg(const OptionParser *state) {
+char* option_parser_peek_next_arg(const OptionParser *state) {
         /* Peek at the next argument, whatever it is (option or position arg).
          * May return NULL. */
 
@@ -360,7 +360,7 @@ char* option_parser_consume_next_arg(OptionParser *state) {
          * so we won't try to interpret it as an option.
          * May return NULL. */
 
-        char *t = option_parser_next_arg(state);
+        char *t = option_parser_peek_next_arg(state);
         if (t)
                 shift_arg(state->argv, state->positional_offset++, state->optind++);
         return t;
@@ -388,6 +388,14 @@ size_t option_parser_get_n_args(const OptionParser *state) {
         return state->argc - state->positional_offset;
 }
 
+char* option_parser_get_arg(const OptionParser *state, size_t i) {
+        assert(state->optind > 0);
+        assert(state->state == OPTION_PARSER_DONE);
+        assert(state->positional_offset <= state->argc);
+
+        return (size_t) (state->argc - state->positional_offset) > i ? state->argv[state->positional_offset + i] : NULL;
+}
+
 char* option_get_synopsis(const Option *opt, const char *joiner, bool show_metavar) {
         assert(opt);
         assert(!(opt->flags & (OPTION_NAMESPACE_MARKER |

src/shared/options.h

@@ -224,11 +224,17 @@ int option_parse(
                         break;                                          \
                 } else
 
-char* option_parser_next_arg(const OptionParser *state);
+/* Those helpers are used *during* option parsing and allow looking at or taking the next item in
+ * the argv array, either an option or a positional parameter. */
+char* option_parser_peek_next_arg(const OptionParser *state);
 char* option_parser_consume_next_arg(OptionParser *state);
 
+/* Those helpers are used *after* option parsing and return the positional arguments (and unparsed
+ * options in case option parsing was stopped early, e.g. via "--"). */
 char** option_parser_get_args(const OptionParser *state);
 size_t option_parser_get_n_args(const OptionParser *state);
+char* option_parser_get_arg(const OptionParser *state, size_t i);
+
 char* option_get_synopsis(const Option *opt, const char *joiner, bool show_metavar);
 
 int _option_parser_get_help_table_full(