6. Argparse Library

The argparse library provides argument parsing functionality, this library makes it easy to write user-friendly command-line program.

6.1. Features and Capabilities

  • Support parsing optional argument (which could take with no-value, required-value and optional-value).
  • Support parsing positional argument (which must take with required-value).
  • Support automatic generate usage information.
  • Support issue errors when provide with invalid arguments.
  • Support parsing argument by two ways:
    1. autosave: used for parsing known value types;
    2. callback: will invoke user callback to parse.

6.2. Usage Guide

The following code demonstrates how to use:

static int
argparse_user_callback(uint32_t index, const char *value, void *opaque)
{
   if (index == 1) {
      /* process "--ddd" argument, because it is configured as no-value,
       * the parameter 'value' is NULL.
       */
      ...
   } else if (index == 2) {
      /* process "--eee" argument, because it is configured as
       * required-value, the parameter 'value' must not be NULL.
       */
      ...
   } else if (index == 3) {
      /* process "--fff" argument, because it is configured as
       * optional-value, the parameter 'value' maybe NULL or not NULL,
       * depend on input.
       */
      ...
   } else if (index == 300) {
      /* process "ppp" argument, because it's a positional argument,
       * the parameter 'value' must not be NULL.
       */
      ...
   } else {
      return -EINVAL;
   }
}

static int aaa_val, bbb_val, ccc_val, ooo_val;

static struct rte_argparse obj = {
   .prog_name = "test-demo",
   .usage = "[EAL options] -- [optional parameters] [positional parameters]",
   .descriptor = NULL,
   .epilog = NULL,
   .exit_on_error = true,
   .callback = argparse_user_callback,
   .args = {
      { "--aaa", "-a", "aaa argument", &aaa_val, (void *)100, RTE_ARGPARSE_ARG_NO_VALUE       | RTE_ARGPARSE_ARG_VALUE_INT },
      { "--bbb", "-b", "bbb argument", &bbb_val, NULL,        RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_VALUE_INT },
      { "--ccc", "-c", "ccc argument", &ccc_val, (void *)200, RTE_ARGPARSE_ARG_OPTIONAL_VALUE | RTE_ARGPARSE_ARG_VALUE_INT },
      { "--ddd", "-d", "ddd argument", NULL,     (void *)1,   RTE_ARGPARSE_ARG_NO_VALUE       },
      { "--eee", "-e", "eee argument", NULL,     (void *)2,   RTE_ARGPARSE_ARG_REQUIRED_VALUE },
      { "--fff", "-f", "fff argument", NULL,     (void *)3,   RTE_ARGPARSE_ARG_OPTIONAL_VALUE },
      { "ooo",   NULL, "ooo argument", &ooo_val, NULL,        RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_VALUE_INT },
      { "ppp",   NULL, "ppp argument", NULL,     (void *)300, RTE_ARGPARSE_ARG_REQUIRED_VALUE },
   },
};

int
main(int argc, char **argv)
{
   ...
   ret = rte_argparse_parse(&obj, argc, argv);
   ...
}

In this example, the arguments which start with a hyphen (-) are optional arguments (they’re “–aaa”/”–bbb”/”–ccc”/”–ddd”/”–eee”/”–fff”); and the arguments which don’t start with a hyphen (-) are positional arguments (they’re “ooo”/”ppp”).

Every argument must be set whether to carry a value (one of RTE_ARGPARSE_ARG_NO_VALUE, RTE_ARGPARSE_ARG_REQUIRED_VALUE and RTE_ARGPARSE_ARG_OPTIONAL_VALUE).

Note

Positional argument must set RTE_ARGPARSE_ARG_REQUIRED_VALUE.

6.2.1. User Input Requirements

For optional arguments which take no-value, the following mode is supported (take above “–aaa” as an example):

  • The single mode: “–aaa” or “-a”.

For optional arguments which take required-value, the following two modes are supported (take above “–bbb” as an example):

  • The kv mode: “–bbb=1234” or “-b=1234”.
  • The split mode: “–bbb 1234” or “-b 1234”.

For optional arguments which take optional-value, the following two modes are supported (take above “–ccc” as an example):

  • The single mode: “–ccc” or “-c”.
  • The kv mode: “–ccc=123” or “-c=123”.

For positional arguments which must take required-value, their values are parsing in the order defined.

Note

The compact mode is not supported. Take above “-a” and “-d” as an example, don’t support “-ad” input.

6.2.2. Parsing by autosave way

Argument of known value type (e.g. RTE_ARGPARSE_ARG_VALUE_INT) could be parsed using this autosave way, and its result will save in the val_saver field.

In the above example, the arguments “–aaa”/”–bbb”/”–ccc” and “ooo” both use this way, the parsing is as follows:

  • For argument “–aaa”, it is configured as no-value, so the aaa_val will be set to val_set field which is 100 in the above example.
  • For argument “–bbb”, it is configured as required-value, so the bbb_val will be set to user input’s value (e.g. will be set to 1234 with input “–bbb 1234”).
  • For argument “–ccc”, it is configured as optional-value, if user only input “–ccc” then the ccc_val will be set to val_set field which is 200 in the above example; if user input “–ccc=123”, then the ccc_val will be set to 123.
  • For argument “ooo”, it is positional argument, the ooo_val will be set to user input’s value.

6.2.3. Parsing by callback way

It could also choose to use callback to parse, just define a unique index for the argument and make the val_save field to be NULL also zero value-type.

In the above example, the arguments “–ddd”/”–eee”/”–fff” and “ppp” both use this way.

6.2.4. Multiple times argument

If want to support the ability to enter the same argument multiple times, then should mark RTE_ARGPARSE_ARG_SUPPORT_MULTI in the flags field. For example:

{ "--xyz", "-x", "xyz argument", NULL, (void *)10, RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_SUPPORT_MULTI },

Then the user input could contain multiple “–xyz” arguments.

Note

The multiple times argument only support with optional argument and must be parsed by callback way.