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