From 46ce0d1b2615dfe4315a9456cfc4e37514fdce68 Mon Sep 17 00:00:00 2001
From: Pierre Esterie <pierre.esterie@inria.fr>
Date: Fri, 7 May 2021 15:30:48 +0200
Subject: [PATCH] Update readmes
---
README.md | 5 ++-
cl_parser/README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 92 insertions(+), 2 deletions(-)
create mode 100644 cl_parser/README.md
diff --git a/README.md b/README.md
index b6e4236..f49f958 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# cpp_tools : small cpp tools to reuse in you projects
+# cpp_tools : small cpp tools to reuse in your projects
`cpp_tools` is a collection of headers organised as modules.
The fisrt effort here, is to use this repository as a submodule in your lib/app.
@@ -77,5 +77,6 @@ And that's it !
## Documentation
-Docs of the modules can be found [here](https://compose.gitlabpages.inria.fr/oldstack/cpp_tools/).
+[cl_parser](cl_parser/README.md)
+:construction: Docs of the modules can be found [here](https://compose.gitlabpages.inria.fr/oldstack/cpp_tools/) (under construction)
diff --git a/cl_parser/README.md b/cl_parser/README.md
new file mode 100644
index 0000000..fb44080
--- /dev/null
+++ b/cl_parser/README.md
@@ -0,0 +1,89 @@
+# Command Line Parser
+
+
+The command line parser allows you to easyly managed command line arguments
+of your programs.
+
+The following features are available :
+ - multiple names for a flag (i.e `--a-very-long-name`, `-shortname`, `--unotherone`, etc)
+ - required flags that force the user to provide a value.
+ - vector of values as input of a flag
+ - automatic `help` flag generation.
+
+## Example
+
+First let's look at the anatomy of a flag.
+It's a simple structure with the following required fields :
+ - `cpp_tools::cl_parser::str_vec flags` : a vector of strings with the different versions of the flag
+ - `const char* description` : the description of the flag that will appear in the help
+ - `using type = float` : the type of the flag
+ - `type def = 1.0` : the default value of the flag (optional)
+
+To use the library, two files are required `cpp_tools/cl_parser/tcli.hpp` and `cpp_tools/cl_parser/help_descriptor.hpp`
+
+Now, let's have a look a a first example :
+
+```cpp
+#include <cpp_tools/cl_parser/tcli.hpp>
+#include <cpp_tools/cl_parser/help_descriptor.hpp>
+
+struct n_count
+{
+ // here, you specify several flags by providing an initializer list of strings
+ // to the flags variable.
+ cpp_tools::cl_parser::str_vec flags = {"--n-count", "-n"};
+ // then, you specify the description of the flag/s
+ const char* description = "An integer to catch.";
+ // register the type of the flag/s
+ using type = int;
+ // put the def variable to the default value of the flag (optional)
+ type def = 1;
+};
+
+// another example with some flaoting point type
+struct delta
+{
+ cpp_tools::cl_parser::str_vec flags = {"--delta", "-d"};
+ const char* description = "Delta to apply.";
+ using type = double;
+ type def = 0.1;
+};
+```
+
+Now let's add a required flag that will throw an exception if not provided :
+
+```cpp
+\\ you need to inherit from required_tag to register your flag as required.
+struct input_file : cpp_tools::cl_parser::required_tag
+{
+ cpp_tools::cl_parser::str_vec flags = {"--input-file", "-fin"};
+ const char* description = "Input filename.";
+ using type = std::string;
+};
+```
+
+After defining all of our flags, we can create our parser :
+
+```cpp
+auto main(int argc, char* argv[]) -> int
+{
+ // Parameter handling, register all your flags and add the help flag for automated help.
+ auto parser = cpp_tools::cl_parser::make_parser( cpp_tools::cl_parser::help{}
+ , n_count{}
+ , delta{}
+ , input_file{});
+
+ // then, we ask the parser to parse argc and argv
+ parser.parse(argc, argv);
+ ...
+}
+```
+Note that we added the `cpp_tools::cl_parser::help{}` flag to generate automaticaly
+the help command line argument.
+
+And finally we can access the flag value as follow :
+
+```cpp
+const auto n_count = parser.get<n_count>();
+const auto file = parser.get<input_file>();
+```
--
GitLab