1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2024 HiSilicon Limited 3 4Argparse Library 5================ 6 7The argparse library provides argument parsing functionality, 8this library makes it easy to write user-friendly command-line program. 9 10Features and Capabilities 11------------------------- 12 13- Support parsing optional argument (which could take with no-value, 14 required-value and optional-value). 15 16- Support parsing positional argument (which must take with required-value). 17 18- Support automatic generate usage information. 19 20- Support issue errors when provide with invalid arguments. 21 22- Support parsing argument by two ways: 23 24 #. autosave: used for parsing known value types; 25 #. callback: will invoke user callback to parse. 26 27Usage Guide 28----------- 29 30The following code demonstrates how to use: 31 32.. code-block:: C 33 34 static int 35 argparse_user_callback(uint32_t index, const char *value, void *opaque) 36 { 37 if (index == 1) { 38 /* process "--ddd" argument, because it is configured as no-value, 39 * the parameter 'value' is NULL. 40 */ 41 ... 42 } else if (index == 2) { 43 /* process "--eee" argument, because it is configured as 44 * required-value, the parameter 'value' must not be NULL. 45 */ 46 ... 47 } else if (index == 3) { 48 /* process "--fff" argument, because it is configured as 49 * optional-value, the parameter 'value' maybe NULL or not NULL, 50 * depend on input. 51 */ 52 ... 53 } else if (index == 300) { 54 /* process "ppp" argument, because it's a positional argument, 55 * the parameter 'value' must not be NULL. 56 */ 57 ... 58 } else { 59 return -EINVAL; 60 } 61 } 62 63 static int aaa_val, bbb_val, ccc_val, ooo_val; 64 65 static struct rte_argparse obj = { 66 .prog_name = "test-demo", 67 .usage = "[EAL options] -- [optional parameters] [positional parameters]", 68 .descriptor = NULL, 69 .epilog = NULL, 70 .exit_on_error = true, 71 .callback = argparse_user_callback, 72 .args = { 73 { "--aaa", "-a", "aaa argument", &aaa_val, (void *)100, RTE_ARGPARSE_ARG_NO_VALUE | RTE_ARGPARSE_ARG_VALUE_INT }, 74 { "--bbb", "-b", "bbb argument", &bbb_val, NULL, RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_VALUE_INT }, 75 { "--ccc", "-c", "ccc argument", &ccc_val, (void *)200, RTE_ARGPARSE_ARG_OPTIONAL_VALUE | RTE_ARGPARSE_ARG_VALUE_INT }, 76 { "--ddd", "-d", "ddd argument", NULL, (void *)1, RTE_ARGPARSE_ARG_NO_VALUE }, 77 { "--eee", "-e", "eee argument", NULL, (void *)2, RTE_ARGPARSE_ARG_REQUIRED_VALUE }, 78 { "--fff", "-f", "fff argument", NULL, (void *)3, RTE_ARGPARSE_ARG_OPTIONAL_VALUE }, 79 { "ooo", NULL, "ooo argument", &ooo_val, NULL, RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_VALUE_INT }, 80 { "ppp", NULL, "ppp argument", NULL, (void *)300, RTE_ARGPARSE_ARG_REQUIRED_VALUE }, 81 }, 82 }; 83 84 int 85 main(int argc, char **argv) 86 { 87 ... 88 ret = rte_argparse_parse(&obj, argc, argv); 89 ... 90 } 91 92In this example, the arguments which start with a hyphen (-) are optional 93arguments (they're "--aaa"/"--bbb"/"--ccc"/"--ddd"/"--eee"/"--fff"); and the 94arguments which don't start with a hyphen (-) are positional arguments 95(they're "ooo"/"ppp"). 96 97Every argument must be set whether to carry a value (one of 98``RTE_ARGPARSE_ARG_NO_VALUE``, ``RTE_ARGPARSE_ARG_REQUIRED_VALUE`` and 99``RTE_ARGPARSE_ARG_OPTIONAL_VALUE``). 100 101.. note:: 102 103 Positional argument must set ``RTE_ARGPARSE_ARG_REQUIRED_VALUE``. 104 105User Input Requirements 106~~~~~~~~~~~~~~~~~~~~~~~ 107 108For optional arguments which take no-value, 109the following mode is supported (take above "--aaa" as an example): 110 111- The single mode: "--aaa" or "-a". 112 113For optional arguments which take required-value, 114the following two modes are supported (take above "--bbb" as an example): 115 116- The kv mode: "--bbb=1234" or "-b=1234". 117 118- The split mode: "--bbb 1234" or "-b 1234". 119 120For optional arguments which take optional-value, 121the following two modes are supported (take above "--ccc" as an example): 122 123- The single mode: "--ccc" or "-c". 124 125- The kv mode: "--ccc=123" or "-c=123". 126 127For positional arguments which must take required-value, 128their values are parsing in the order defined. 129 130.. note:: 131 132 The compact mode is not supported. 133 Take above "-a" and "-d" as an example, don't support "-ad" input. 134 135Parsing by autosave way 136~~~~~~~~~~~~~~~~~~~~~~~ 137 138Argument of known value type (e.g. ``RTE_ARGPARSE_ARG_VALUE_INT``) 139could be parsed using this autosave way, 140and its result will save in the ``val_saver`` field. 141 142In the above example, the arguments "--aaa"/"--bbb"/"--ccc" and "ooo" 143both use this way, the parsing is as follows: 144 145- For argument "--aaa", it is configured as no-value, 146 so the ``aaa_val`` will be set to ``val_set`` field 147 which is 100 in the above example. 148 149- For argument "--bbb", it is configured as required-value, 150 so the ``bbb_val`` will be set to user input's value 151 (e.g. will be set to 1234 with input "--bbb 1234"). 152 153- For argument "--ccc", it is configured as optional-value, 154 if user only input "--ccc" then the ``ccc_val`` will be set to ``val_set`` field 155 which is 200 in the above example; 156 if user input "--ccc=123", then the ``ccc_val`` will be set to 123. 157 158- For argument "ooo", it is positional argument, 159 the ``ooo_val`` will be set to user input's value. 160 161Parsing by callback way 162~~~~~~~~~~~~~~~~~~~~~~~ 163 164It could also choose to use callback to parse, 165just define a unique index for the argument 166and make the ``val_save`` field to be NULL also zero value-type. 167 168In the above example, the arguments "--ddd"/"--eee"/"--fff" and "ppp" both use this way. 169 170Multiple times argument 171~~~~~~~~~~~~~~~~~~~~~~~ 172 173If want to support the ability to enter the same argument multiple times, 174then should mark ``RTE_ARGPARSE_ARG_SUPPORT_MULTI`` in the ``flags`` field. 175For example: 176 177.. code-block:: C 178 179 { "--xyz", "-x", "xyz argument", NULL, (void *)10, RTE_ARGPARSE_ARG_REQUIRED_VALUE | RTE_ARGPARSE_ARG_SUPPORT_MULTI }, 180 181Then the user input could contain multiple "--xyz" arguments. 182 183.. note:: 184 185 The multiple times argument only support with optional argument 186 and must be parsed by callback way. 187