1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
|
.. 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.
|
