xref: /dpdk/doc/guides/prog_guide/argparse_lib.rst (revision 51a639ca804234462df0a8c72523fa71181cea24)

.. SPDX-License-Identifier: BSD-3-Clause
   Copyright(c) 2024 HiSilicon Limited

Argparse Library
================

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

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:

  #. autosave: used for parsing known value types;
  #. callback: will invoke user callback to parse.

Usage Guide
-----------

The following code demonstrates how to use:

.. code-block:: C

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

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.

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.

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.

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:

.. code-block:: C

   { "--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.