When the arguments passed to argparse include -h/--help then usage
information is automatically printed. Provide the capability for the
user to supply their own help function for this.
Signed-off-by: Bruce Richardson <bruce.richard...@intel.com>
---
doc/guides/prog_guide/argparse_lib.rst | 16 ++++++++++++++++
doc/guides/rel_notes/release_25_11.rst | 7 +++++++
lib/argparse/rte_argparse.c | 5 ++++-
lib/argparse/rte_argparse.h | 7 ++++++-
4 files changed, 33 insertions(+), 2 deletions(-)
diff --git a/doc/guides/prog_guide/argparse_lib.rst
b/doc/guides/prog_guide/argparse_lib.rst
index 9f11714890..b309260d20 100644
--- a/doc/guides/prog_guide/argparse_lib.rst
+++ b/doc/guides/prog_guide/argparse_lib.rst
@@ -24,6 +24,8 @@ Features and Capabilities
#. autosave: used for parsing known value types;
#. callback: will invoke user callback to parse.
+- Supports automatic help and usage information.
+
Usage Guide
-----------
@@ -193,3 +195,17 @@ Then the user input could contain multiple ``--xyz``
arguments.
The multiple times argument only support with optional argument
and must be parsed by callback way.
+
+Help and Usage Information
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The argparse library supports automatic generation of help and usage
information.
+When the input arguments include ``-h`` or ``--help``,
+it will print the usage information to standard output.
+If the default help output is not what is wanted,
+the user can provide a custom help printing function by setting the
``print_help`` field in the ``rte_argparse`` object.
+(If this field is set to NULL, the default help printing function will be
used.)
+
+If the custom help printing function wants to use the text produced by the
default help function,
+it can call the function ``rte_argparse_print_help()`` to get the help text
printed to an output stream,
+for example: stdout or stderr.
diff --git a/doc/guides/rel_notes/release_25_11.rst
b/doc/guides/rel_notes/release_25_11.rst
index ccad6d89ff..75bbd0e821 100644
--- a/doc/guides/rel_notes/release_25_11.rst
+++ b/doc/guides/rel_notes/release_25_11.rst
@@ -55,6 +55,13 @@ New Features
Also, make sure to start the actual text at the margin.
=======================================================
+* **Allow overriding the automatic usage/help generation in argparse library.**
+
+ The argparse library now supports overriding the automatic help text
generation,
+ by allowing the user to provide a custom function to generate the output
text.
+ The built-in help text function is available as a public function which can
be reused by custom functions,
+ if so desired.
+
Removed Items
-------------
diff --git a/lib/argparse/rte_argparse.c b/lib/argparse/rte_argparse.c
index d3b32c6357..e7b9bf573d 100644
--- a/lib/argparse/rte_argparse.c
+++ b/lib/argparse/rte_argparse.c
@@ -821,7 +821,10 @@ rte_argparse_parse(const struct rte_argparse *obj, int
argc, char **argv)
goto error;
if (show_help) {
- rte_argparse_print_help(stdout, obj);
+ if (obj->print_help != NULL)
+ obj->print_help(obj);
+ else
+ rte_argparse_print_help(stdout, obj);
exit(0);
}
diff --git a/lib/argparse/rte_argparse.h b/lib/argparse/rte_argparse.h
index baf278f6b9..63b49ba220 100644
--- a/lib/argparse/rte_argparse.h
+++ b/lib/argparse/rte_argparse.h
@@ -160,8 +160,13 @@ struct rte_argparse {
rte_arg_parser_t callback;
/** Opaque which used to invoke callback. */
void *opaque;
+ /**
+ * Function pointer for printing usage when -h is passed.
+ * If this is NULL, default printing function will be used.
+ */
+ void (*print_help)(const struct rte_argparse *obj);
/** Reserved field used for future extension. */
- void *reserved[16];
+ void *reserved[15];
/** Arguments configuration. Must ended with ARGPARSE_ARG_END(). */
struct rte_argparse_arg args[];
};
--
2.48.1
