1. Argparse Library

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

1.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.

1.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.

1.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.

1.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.

1.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.

1.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.