general/CLI11
2
0
Fork 0
mirror of https://github.com/CLIUtils/CLI11.git synced 2026-01-19 04:52:08 +00:00
Code Issues Projects Releases Wiki Activity

Moving tutorial docs (#304)

Browse Source
This commit is contained in:
Henry Schreiner
2019-09-06 14:25:27 -04:00
committed by GitHub
parent cf4933db91
commit 4917b8b763
24 changed files with 5853 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
.travis.yml
View File

@@ -25,6 +25,8 @@ matrix:
# Docs and clang 3.5
- compiler: clang
language: node_js
node_js: "7.4.0"
env:
- DEPLOY_MAT=yes
addons:
@@ -34,6 +36,9 @@ matrix:
install:
- export CC=clang-3.5
- export CXX=clang++-3.5
- npm install gitbook-cli -g
- gitbook fetch 3.2.3
- (cd book && gitbook install)
script:
- .ci/make_and_test.sh 11
after_success:
@@ -45,6 +50,7 @@ matrix:
. .ci/build_doxygen.sh
.ci/build_docs.sh
fi
- (cd book && gitbook build . ../docs/html/book)
# GCC 7 and coverage (8 does not support lcov, wait till 9 and new lcov)
- compiler: gcc

20
book/.gitignore vendored Normal file
View File

@@ -0,0 +1,20 @@
# Node rules:
## Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
.grunt
## Dependency directory
## Commenting this out is preferred by some people, see
## https://docs.npmjs.com/misc/faq#should-i-check-my-node_modules-folder-into-git
node_modules
# Book build output
_book
# eBook build output
*.epub
*.mobi
*.pdf
a.out
*build*

71
book/README.md Normal file
View File

@@ -0,0 +1,71 @@
# CLI11: An introduction
This gitbook is designed to provide an introduction to using the CLI11 library to write your own command line programs. The library is designed to be clean, intuitive, but powerful. There are no requirements beyond C++11 support (and even `<regex>` support not required). It works on Mac, Linux, and Windows, and has 100% test coverage on all three systems. You can simply drop in a single header file (`CLI11.hpp` available in [releases]) to use CLI11 in your own application. Other ways to integrate it into a build system are listed in the [README].
The library was inspired the Python libraries [Plumbum] and [Click], and incorporates many of their user friendly features. The library is extensively documented, with a [friendly introduction][README], this tutorial book, and more technical [API docs].
> Feel free to contribute to [this documentation here][CLI11Tutorial] if something can be improved!
The syntax is simple and scales from a basic application to a massive physics analysis with multiple models and many parameters and switches. For example, this is a simple program that has an optional parameter that defaults to 1:
```term
gitbook $ ./a.out
Parameter value: 0
gitbook $ ./a.out -p 4
Parameter value: 4
gitbook $ ./a.out --help
App description
Usage: ./a.out [OPTIONS]
Options:
-h,--help Print this help message and exit
-p INT Parameter
```
Like any good command line application, help is provided. This program can be implemented in 10 lines:
[include](code/intro.cpp)
[Source code](https://gitlab.com/CLIUtils/CLI11Tutorial/blob/master/code/intro.cpp)
Unlike some other libraries, this is enough to exit correctly and cleanly if help is requested or if incorrect arguments are passed. You can try this example out for yourself. To compile with GCC:
```term
gitbook:examples $ c++ -std=c++11 intro.cpp
```
Much more complicated options are handled elegantly:
```cpp
std::string req_real_file;
app.add_option("-f,--file", file, "Require an existing file")
->required()
->check(CLI::ExistingFile);
```
You can use any valid type; the above example could have used a `boost::file_system` file instead of a `std::string`. The value is a real value and does not require any special lookups to access. You do not have to risk typos by repeating the values after parsing like some libraries require. The library also handles positional arguments, flags, fixed or unlimited repeating options, interdependent options, flags, custom validators, help groups, and more.
You can use subcommands, as well. Subcommands support callback lambda functions when parsed, or they can be checked later. You can infinitely nest subcommands, and each is a full `App` instance, supporting everything listed above.
Reading/producing `.ini` files for configuration is also supported, as is using environment variables as input. The base `App` can be subclassed and customized for use in a toolkit (like [GooFit]). All the standard shell idioms, like `--`, work as well.
CLI11 was developed at the [University of Cincinnati] in support of the [GooFit] library under [NSF Award 1414736][NSF 1414736]. It was featured in a [DIANA/HEP] meeting at CERN. Please give it a try! Feedback is always welcome.
This guide was based on CLI11 1.7.
[GooFit]: https://github.com/GooFit/GooFit
[DIANA/HEP]: http://diana-hep.org
[CLI11]: https://github.com/CLIUtils/CLI11
[CLI11Tutorial]: https://gitlab.com/CLIUtils/CLI11Tutorial
[releases]: https://github.com/CLIUtils/CLI11/releases
[API docs]: https://cliutils.github.io/CLI11
[README]: https://github.com/CLIUtils/CLI11/blob/master/README.md
[NSF 1414736]: https://nsf.gov/awardsearch/showAward?AWD_ID=1414736
[University of Cincinnati]: http://www.uc.edu
[Plumbum]: http://plumbum.readthedocs.io/en/latest/
[Click]: http://click.pocoo.org/5/

16
book/SUMMARY.md Normal file
View File

@@ -0,0 +1,16 @@
# Summary
* [Introduction](/README.md)
* [Installation](/chapters/installation.md)
* [Basics](/chapters/basics.md)
* [Flags](/chapters/flags.md)
* [Options](/chapters/options.md)
* [Validators](/chapters/validators.md)
* [Subcommands and the App](/chapters/subcommands.md)
* [An advanced example](/chapters/an-advanced-example.md)
* [Configuration files](/chapters/config.md)
* [Formatting help output](/chapters/formatting.md)
* [Toolkits](/chapters/toolkits.md)
* [Advanced topics](/chapters/advanced-topics.md)
* [Internals](/chapters/internals.md)

16
book/book.json Normal file
View File

@@ -0,0 +1,16 @@
{
"title": "CLI11 Tutorial",
"description": "A set of examples and detailed information about CLI11",
"author": "Henry Schreiner",
"plugins": [
"include-codeblock",
"term",
"hints"
],
"pluginsConfig": {
"include-codeblock": {
"unindent": true,
"fixlang": true
}
}
}

138
book/chapters/advanced-topics.md Normal file
View File

@@ -0,0 +1,138 @@
# Advanced topics
## Environment variables
Environment variables can be used to fill in the value of an option:
```cpp
std::string opt;
app.add_option("--my_option", opt)->envname("MY_OPTION");
```
If not given on the command line, the environment variable will be checked and read from if it exists. All the standard tools, like default and required, work as expected.
If passed on the command line, this will ignore the environment variable.
## Needs/excludes
You can set a network of requirements. For example, if flag a needs flag b but cannot be given with flag c, that would be:
```cpp
auto a = app.add_flag("-a");
auto b = app.add_flag("-b");
auto c = app.add_flag("-c");
a->needs(b);
a->excludes(c);
```
CLI11 will make sure your network of requirements makes sense, and will throw an error immediately if it does not.
## Custom option callbacks
You can make a completely generic option with a custom callback. For example, if you wanted to add a complex number (already exists, so please don't actually do this):
```cpp
CLI::Option *
add_option(CLI::App &app, std::string name, cx &variable, std::string description = "", bool defaulted = false) {
CLI::callback_t fun = [&variable](CLI::results_t res) {
double x, y;
bool worked = CLI::detail::lexical_cast(res[0], x) && CLI::detail::lexical_cast(res[1], y);
if(worked)
variable = cx(x, y);
return worked;
};
CLI::Option *opt = app.add_option(name, fun, description, defaulted);
opt->set_custom_option("COMPLEX", 2);
if(defaulted) {
std::stringstream out;
out << variable;
opt->set_default_str(out.str());
}
return opt;
}
```
Then you could use it like this:
```
std::complex<double> comp{0, 0};
add_option(app, "-c,--complex", comp);
```
## Custom converters
You can add your own converters to allow CLI11 to accept more option types in the standard calls. These can only be used for "single" size options (so complex, vector, etc. are a separate topic). If you set up a custom `istringstream& operator <<` overload before include CLI11, you can support different conversions. If you place this in the CLI namespace, you can even keep this from affecting the rest of your code. Here's how you could add `boost::optional` for a compiler that does not have `__has_include`:
```cpp
// CLI11 already does this if __has_include is defined
#ifndef __has_include
#include <boost/optional.hpp>
// Use CLI namespace to avoid the conversion leaking into your other code
namespace CLI {
template <typename T> std::istringstream &operator>>(std::istringstream &in, boost::optional<T> &val) {
T v;
in >> v;
val = v;
return in;
}
}
#endif
#include <CLI11.hpp>
```
This is an example of how to use the system only; if you are just looking for a way to activate `boost::optional` support on older compilers, you should define `CLI11_BOOST_OPTIONAL` before including a CLI11 file, you'll get the `boost::optional` support.
## Custom converters and type names: std::chrono example
An example of adding a custom converter and typename for `std::chrono` follows:
```cpp
namespace CLI
{
template <typename T, typename R>
std::istringstream &operator>>(std::istringstream &in, std::chrono::duration<T,R> &val)
{
T v;
in >> v;
val = std::chrono::duration<T,R>(v);
return in;
}
template <typename T, typename R>
std::stringstream &operator<<(std::stringstream &in, std::chrono::duration<T,R> &val)
{
in << val.count();
return in;
}
}
#include <CLI/CLI.hpp>
namespace CLI
{
namespace detail
{
template <>
constexpr const char *type_name<std::chrono::hours>()
{
return "TIME [H]";
}
template <>
constexpr const char *type_name<std::chrono::minutes>()
{
return "TIME [MIN]";
}
}
}
```
Thanks to Olivier Hartmann for the example.

33
book/chapters/an-advanced-example.md Normal file
View File

@@ -0,0 +1,33 @@
# Making a git clone
Let's try our hand at a little `git` clone, called `geet`. It will just print it's intent, rather than running actual code, since it's just a demonstration. Let's start by adding an app and requiring 1 subcommand to run:
[include:"Intro"](../code/geet.cpp)
Now, let's define the first subcommand, `add`, along with a few options:
[include:"Add"](../code/geet.cpp)
Now, let's add `commit`:
[include:"Commit"](../code/geet.cpp)
All that's need now is the parse call. We'll print a little message after the code runs, and then return:
[include:"Parse"](../code/geet.cpp)
[Source code](https://gitlab.com/CLIUtils/CLI11Tutorial/blob/master/code/flags.cpp)
If you compile and run:
```term
gitbook:examples $ c++ -std=c++11 geet.cpp -o geet
```
You'll see it behaves pretty much like `git`.
## Multi-file App parse code
This example could be made much nicer if it was split into files, one per subcommand. If you simply use shared pointers instead of raw values in the lambda capture, you can tie the lifetime to the lambda function lifetime. CLI11 has a multifile example in its example folder.

27
book/chapters/basics.md Normal file
View File

@@ -0,0 +1,27 @@
# The Basics
The simplest CLI11 program looks like this:
[include](../code/simplest.cpp)
The first line includes the library; this explicitly uses the single file edition (see [Selecting an edition](/chapters/installation)).
After entering the main function, you'll see that a `CLI::App` object is created. This is the basis for all interactions with the library. You could optionally provide a description for your app here.
A normal CLI11 application would define some flags and options next. This is a simplest possible example, so we'll go on.
The macro `CLI11_PARSE` just runs five simple lines. This internally runs `app.parse(argc, argv)`, which takes the command line info from C++ and parses it. If there is an error, it throws a `ParseError`; if you catch it, you can use `app.exit` with the error as an argument to print a nice message and produce the correct return code for your application.
If you just use `app.parse` directly, your application will still work, but the stack will not be correctly unwound since you have an uncaught exception, and the command line output will be cluttered, especially for help.
For this (and most of the examples in this book) we will assume that we have the `CLI11.hpp` file in the current directory and that we are creating an output executable `a.out` on a macOS or Linux system. The commands to compile and test this example would be:
```term
gitbook:examples $ g++ -std=c++11 simplest.cpp
gitbook:examples $ ./a.out -h
Usage: ./a.out [OPTIONS]
Options:
-h,--help Print this help message and exit
```

53
book/chapters/config.md Normal file
View File

@@ -0,0 +1,53 @@
# Accepting configure files
## Reading a configure file
You can tell your app to allow configure files with `set_config("--config")`. There are arguments: the first is the option name. If empty, it will clear the config flag. The second item is the default file name. If that is specified, the config will try to read that file. The third item is the help string, with a reasonable default, and the final argument is a boolean (default: false) that indicates that the configuration file is required and an error will be thrown if the file
is not found and this is set to true.
## Configure file format
Here is an example configuration file, in INI format:
```ini
; Commments are supported, using a ;
; The default section is [default], case insensitive
value = 1
str = "A string"
vector = 1 2 3
; Section map to subcommands
[subcommand]
in_subcommand = Wow
sub.subcommand = true
```
Spaces before and after the name and argument are ignored. Multiple arguments are separated by spaces. One set of quotes will be removed, preserving spaces (the same way the command line works). Boolean options can be `true`, `on`, `1`, `yes`; or `false`, `off`, `0`, `no` (case insensitive). Sections (and `.` separated names) are treated as subcommands (note: this does not mean that subcommand was passed, it just sets the "defaults".
## Writing out a configure file
To print a configuration file from the passed arguments, use `.config_to_str(default_also=false, prefix="", write_description=false)`, where `default_also` will also show any defaulted arguments, `prefix` will add a prefix, and `write_description` will include option descriptions.
## Custom formats
{% hint style='info' %}
New in CLI11 1.6
{% endhint %}
You can invent a custom format and set that instead of the default INI formatter. You need to inherit from `CLI::Config` and implement the following two functions:
```cpp
std::string to_config(const CLI::App *app, bool default_also, bool, std::string) const;
std::vector<CLI::ConfigItem> from_config(std::istream &input) const;
```
The `CLI::ConfigItem`s that you return are simple structures with a name, a vector of parents, and a vector of results. A optionally customizable `to_flag` method on the formatter lets you change what happens when a ConfigItem turns into a flag.
Finally, set your new class as new config formatter:
```cpp
app.config_formatter(std::make_shared<NewConfig>());
```
See [`examples/json.cpp`](https://github.com/CLIUtils/CLI11/blob/master/examples/json.cpp) for a complete JSON config example.

100
book/chapters/flags.md Normal file
View File

@@ -0,0 +1,100 @@
# Adding Flags
The most basic addition to a command line program is a flag. This is simply something that does not take any arguments. Adding a flag in CLI11 is done in one of three ways.
## Boolean flags
The simplest way to add a flag is probably a boolean flag:
```cpp
bool my_flag;
app.add_flag("-f", my_flag, "Optional description");
```
This will bind the flag `-f` to the boolean `my_flag`. After the parsing step, `my_flag` will be `false` if the flag was not found on the command line, or `true` if it was. By default, it will be allowed any number of times, but if you explicitly[^1] request `->take_last(false)`, it will only be allowed once; passing something like `./my_app -f -f` or `./my_app -ff` will throw a `ParseError` with a nice help description.
## Integer flags
If you want to allow multiple flags, simply use any integer-like instead of a bool:
```cpp
int my_flag;
app.add_flag("-f", my_flag, "Optional description");
```
After the parsing step, `my_flag` will contain the number of times this flag was found on the command line, including 0 if not found.
## Pure flags
Every command that starts with `add_`, such as the flag commands, return a pointer to the internally stored `CLI::Option` that describes your addition. If you prefer, you can capture this pointer and use it, and that allows you to skip adding a variable to bind to entirely:
```cpp
CLI::Option* my_flag = app.add_flag("-f", "Optional description");
```
After parsing, you can use `my_flag->count()` to count the number of times this was found. You can also directly use the value (`*my_flag`) as a bool. `CLI::Option` will be discussed in more detail later.
## Callback flags
If you want to define a callback that runs when you make a flag, you can use `add_flag_function` (C++11 or newer) or `add_flag` (C++14 or newer only) to add a callback function. The function should have the signature `void(size_t)`. This could be useful for a version printout, etc.
```
auto callback = [](int count){std::cout << "This was called " << count << " times";};
app.add_flag_function("-c", callback, "Optional description");
```
## Aliases
The name string, the first item of every `add_` method, can contain as many short and long names as you want, separated by commas. For example, `"-a,--alpha,-b,--beta"` would allow any of those to be recognized on the command line. If you use the same name twice, or if you use the same name in multiple flags, CLI11 will immediately throw a `CLI::ConstructionError` describing your problem (it will not wait until the parsing step).
If you want to make an option case insensitive, you can use the `->ignore_case()` method on the `CLI::Option` to do that. For example,
```cpp
bool flag;
app.add_flag("--flag", flag)
->ignore_case();
```
would allow the following to count as passing the flag:
```term
gitbook $ ./my_app --fLaG
```
## Example
The following program will take several flags:
[include:"define"](../code/flags.cpp)
The values would be used like this:
[include:"usage"](../code/flags.cpp)
[Source code](https://gitlab.com/CLIUtils/CLI11Tutorial/blob/master/code/flags.cpp)
If you compile and run:
```term
gitbook:examples $ g++ -std=c++11 flags.cpp
gitbook:examples $ ./a.out -h
Flag example program
Usage: ./a.out [OPTIONS]
Options:
-h,--help Print this help message and exit
-b,--bool This is a bool flag
-i,--int This is an int flag
-p,--plain This is a plain flag
gitbook:examples $ ./a.out -bii --plain -i
The flags program
Bool flag passed
Flag int: 3
Flag plain: 1
```
[^1] It will not inherit this from the parent defaults, since this is often useful even if you don't want all options to allow multiple passed options.

78
book/chapters/formatting.md Normal file
View File

@@ -0,0 +1,78 @@
# Formatting help output
{% hint style='info' %}
New in CLI11 1.6
{% endhint %}
## Customizing an existing formatter
In CLI11, you can control the output of the help printout in full or in part. The default formatter was written in such a way as to be customizable. You can use `app.get_formatter()` to get the current formatter. The formatter you set will be inherited by subcommands that are created after you set the formatter.
There are several configuration options that you can set:
| Set method | Description | Availability |
|------------|-------------|--------------|
| `column_width(width)` | The width of the columns | Both |
| `label(key, value)` | Set a label to a different value | Both |
Labels will map the built in names and type names from key to value if present. For example, if you wanted to change the width of the columns to 40 and the `REQUIRED` label from `(REQUIRED)` to `(MUST HAVE)`:
```cpp
app.get_formatter()->column_width(40);
app.get_formatter()->label("REQUIRED", "(MUST HAVE)");
```
## Subclassing
You can further configure pieces of the code while still keeping most of the formatting intact by subclassing either formatter and replacing any of the methods with your own. The formatters use virtual functions most places, so you are free to add or change anything about them. For example, if you wanted to remove the info that shows up between the option name and the description:
```cpp
class MyFormatter : public CLI::Formatter {
public:
std::string make_opts(const CLI::Option *) const override {return "";}
};
app.formatter(std::make_shared<MyFormatter>());
```
Look at the class definitions in `FormatterFwd.hpp` or the method definitions in `Formatter.hpp` to see what methods you have access to and how they are put together.
## Anatomy of a help message
This is a normal printout, with `<>` indicating the methods used to produce each line.
```
<make_description(app)>
<make_usage(app)>
<make_positionals(app)>
<make_group(app, "Positionals", true, filter>
<make_groups(app, mode)>
<make_group(app, "Option Group 1"), false, filter>
<make_group(app, "Option Group 2"), false, filter>
...
<make_subcommands(app)>
<make_subcommand(sub1, Mode::Normal)>
<make_subcommand(sub2, Mode::Normal)>
<make_footer(app)>
```
`make_usage` calls `make_option_usage(opt)` on all the positionals to build that part of the line. `make_subcommand` passes the subcommand as the app pointer.
The `make_groups` print the group name then call `make_option(o)` on the options listed in that group. The normal printout for an option looks like this:
```
make_option_opts(o)
┌───┴────┐
-n,--name (REQUIRED) This is a description
└────┬────┘ └──────────┬──────────┘
make_option_name(o,p) make_option_desc(o)
```
Notes:
* `*1`: This signature depends on whether the call is from a positional or optional.
* `o` is opt pointer, `p` is true if positional.

91
book/chapters/installation.md Normal file
View File

@@ -0,0 +1,91 @@
# Installation
## Single file edition
```cpp
#include <CLI11.hpp>
```
This example uses the single file edition of CLI11. You can download `CLI11.hpp` from the latest release and put it into the same folder as your source code, then compile this with C++ enabled. For a larger project, you can just put this in an include folder and you are set.
## Full edition
```cpp
#include <CLI/CLI.hpp>
```
If you want to use CLI11 in its full form, you can also use the original multiple file edition. This has an extra utility (`Timer`), and is does not require that you use a release. The only change to your code would be the include shown above.
### CMake support for the full edition
If you use CMake 3.4+ for your project (highly recommended), CLI11 comes with a powerful CMakeLists.txt file that was designed to also be used with `add_subproject`. You can add the repository to your code (preferably as a git submodule), then add the following line to your project (assuming your folder is called CLI11):
```cmake
add_subdirectory(CLI11)
```
Then, you will have a target `CLI11::CLI11` that you can link to with `target_link_libraries`. It will provide the include paths you need for the library. This is the way [GooFit](https://github.com/GooFit/GooFit) uses CLI11, for example.
You can also configure and optionally install CLI11, and CMake will create the necessary `lib/cmake/CLI11/CLI11Config.cmake` files, so `find_package(CLI11 CONFIG REQUIRED)` also works.
If you use conan.io, CLI11 supports that too.
### Running tests on the full edition
CLI11 has examples and tests that can be accessed using a CMake build on any platform. Simply build and run ctest to run the 200+ tests to ensure CLI11 works on your system.
As an example of the build system, the following code will download and test CLI11 in a simple Alpine Linux docker container [^1]:
```term
gitbook:~ $ docker run -it alpine
root:/ # apk add --no-cache g++ cmake make git
fetch ...
root:/ # git clone https://github.com/CLIUtils/CLI11.git
Cloning into 'CLI11' ...
root:/ # cd CLI11
root:CLI11 # mkdir build
root:CLI11 # cd build
root:build # cmake ..
-- The CXX compiler identification is GNU 6.3.0 ...
root:build # make
Scanning dependencies ...
root:build # make test
[warning]Running tests...
Test project /CLI11/build
Start 1: HelpersTest
1/10 Test #1: HelpersTest ...................... Passed 0.01 sec
Start 2: IniTest
2/10 Test #2: IniTest .......................... Passed 0.01 sec
Start 3: SimpleTest
3/10 Test #3: SimpleTest ....................... Passed 0.01 sec
Start 4: AppTest
4/10 Test #4: AppTest .......................... Passed 0.02 sec
Start 5: CreationTest
5/10 Test #5: CreationTest ..................... Passed 0.01 sec
Start 6: SubcommandTest
6/10 Test #6: SubcommandTest ................... Passed 0.01 sec
Start 7: HelpTest
7/10 Test #7: HelpTest ......................... Passed 0.01 sec
Start 8: NewParseTest
8/10 Test #8: NewParseTest ..................... Passed 0.01 sec
Start 9: TimerTest
9/10 Test #9: TimerTest ........................ Passed 0.24 sec
Start 10: link_test_2
10/10 Test #10: link_test_2 ...................... Passed 0.00 sec
100% tests passed, 0 tests failed out of 10
Total Test time (real) = 0.34 sec
```
For the curious, the CMake options and defaults are listed below. Most options default to off if CLI11 is used as a subdirectory in another project.
| Option | Description |
|--------|-------------|
| `CLI11_SINGLE_FILE=ON` | Build the `CLI11.hpp` file from the sources. Requires Python (version 3 or 2.7). |
| `CLI11_SINGLE_FILE_TESTS=OFF` | Run the tests on the generated single file version as well |
| `CLI11_EXAMPLES=ON` | Build the example programs. |
| `CLI11_TESTING=ON` | Build the tests. |
| `CLANG_TIDY_FIX=OFF` | Run `clang-tidy` on the examples and headers and apply fixes. (Changes source code!) Requires LLVM and CMake 3.6+. |
[^1]: Docker is being used to create a pristine disposable environment; there is nothing special about this container. Alpine is being used because it is small, modern, and fast. Commands are similar on any other platform.

45
book/chapters/internals.md Normal file
View File

@@ -0,0 +1,45 @@
# CLI11 Internals
## Callbacks
The library was designed to bind to existing variables without requiring typed classes or inheritance. This is accomplished through lambda functions.
This looks like:
```cpp
Option* add_option(string name, T item) {
this->function = [&item](string value){
item = detail::lexical_cast<T>(value);
}
}
```
Obviously, you can't access `T` after the `add_` method is over, so it stores the string representation of the default value if it receives the special `true` value as the final argument (not shown above).
## Parsing
Parsing follows the following procedure:
1. `_validate`: Make sure the defined options are self consistent.
2. `_parse`: Main parsing routine. See below.
3. `_run_callback`: Run an App callback if present.
The parsing phase is the most interesting:
1. `_parse_single`: Run on each entry on the command line and fill the options/subcommands.
2. `_process`: Run the procedure listed below.
3. `_process_extra`: This throws an error if needed on extra arguments that didn't fit in the parse.
The `_process` procedure runs the following steps; each step is recursive and completes all subcommands before moving to the next step (new in 1.7). This ensures that interactions between options and subcommand options is consistent.
1. `_process_ini`: This reads an INI file and fills/changes options as needed.
2. `_process_env`: Look for environment variables.
3. `_process_callbacks`: Run the callback functions - this fills out the variables.
4. `_process_help_flags`: Run help flags if present (and quit).
5. `_process_requirements`: Make sure needs/excludes, required number of options present.
## Exceptions
The library immediately returns a C++ exception when it detects a problem, such as an incorrect construction or a malformed command line.

183
book/chapters/options.md Normal file
View File

@@ -0,0 +1,183 @@
# Options
## Simple options
The most versatile addition to a command line program is a option. This is like a flag, but it takes an argument. CLI11 handles all the details for many types of options for you, based on their type. To add an option:
```cpp
int int_option;
app.add_option("-i", int_option, "Optional description");
```
This will bind the option `-i` to the integer `int_option`. On the command line, a single value that can be converted to an integer will be expected. Non-integer results will fail. If that option is not given, CLI11 will not touch the initial value. This allows you to set up defaults by simply setting your value beforehand. If you want CLI11 to display your default value, you can add the optional final argument `true` when you add the option. If you do not add this, you do not even need your option value to be printable[^1].
```cpp
int int_option = 0;
app.add_option("-i", int_option, "Optional description", true);
```
You can use any C++ int-like type, not just `int`. CLI11 understands the following categories of types:
| Type | CLI11 |
|-------------|-------|
| int-like | Integer conversion up to 64-bit, can be unsigned |
| float-like | Floating point conversions |
| string-like | Anything else that can be shifted into a StringStream |
| vector-like | A vector of the above three types (see below) |
| function | A function that takes an array of strings and returns a string that describes the conversion failure or empty for success. May be the empty function. (`{}`) |
By default, CLI11 will assume that an option is optional, and one value is expected if you do not use a vector. You can change this on a specific option using option modifiers.
## Positional options and aliases
When you give an option on the command line without a name, that is a positional option. Positional options are accepted in the same order they are defined. So, for example:
```term
gitbook:examples $ ./a.out one --two three four
```
The string `one` would have to be the first positional option. If `--two` is a flag, then the remaining two strings are positional. If `--two` is a one-argument option, then `four` is the second positional. If `--two` accepts two or more arguments, then there are no more positionals.
To make a positional option, you simply give CLI11 one name that does not start with a dash. You can have as many (non-overlapping) names as you want for an option, but only one positional name. So the following name string is valid:
```cpp
"-a,-b,--alpha,--beta,mypos"
```
This would make two short option aliases, two long option alias, and the option would be also be accepted as a positional.
## Vectors of options
If you use a vector instead of a plain option, you can accept more than one value on the command line. By default, a vector accepts as many options as possible, until the next value that could be a valid option name. You can specify a set number using an option modifier `->expected(N)`. (The default unlimited behavior on vectors is restore with `N=-1`) CLI11 does not differentiate between these two methods for unlimited acceptance options:[^2]
| Separate names | Combined names |
|-------------------|-----------------|
| `--vec 1 --vec 2` | `--vec 1 2` |
The original version did allow the option system to access information on the grouping of options received, but was removed for simplicity.
An example of setting up a vector option:
```cpp
std::vector<int> int_vec;
app.add_option("--vec", int_vec, "My vector option");
```
Vectors will be replaced by the parsed content if the option is given on the command line.
## Option modifiers
When you call `add_option`, you get a pointer to the added option. You can use that to add option modifiers. A full listing of the option modifiers:
| Modifier | Description |
|----------|-------------|
| `->required()`| The program will quit if this option is not present. This is `mandatory` in Plumbum, but required options seems to be a more standard term. For compatibility, `->mandatory()` also works. |
| `->expected(N)`| Take `N` values instead of as many as possible, only for vector args.|
| `->needs(opt)`| This option requires another option to also be present, opt is an `Option` pointer.|
| `->excludes(opt)`| This option cannot be given with `opt` present, opt is an `Option` pointer.|
| `->envname(name)`| Gets the value from the environment if present and not passed on the command line.|
| `->group(name)`| The help group to put the option in. No effect for positional options. Defaults to `"Options"`. `"Hidden"` will not show up in the help print.|
| `->ignore_case()`| Ignore the case on the command line (also works on subcommands, does not affect arguments).|
| `->ignore_underscore()`| Ignore any underscores on the command line (also works on subcommands, does not affect arguments, new in CLI11 1.7).|
| `->multi_option_policy(CLI::MultiOptionPolicy::Throw)` | Sets the policy if 1 argument expected but this was received on the command line several times. `Throw`ing an error is the default, but `TakeLast`, `TakeFirst`, and `Join` are also available. See the next three lines for shortcuts to set this more easily. |
| `->take_last()` | Only use the last option if passed several times. This is always true by default for bool options, regardless of the app default, but can be set to false explicitly with `->multi_option_policy()`.|
| `->take_first()` | sets `->multi_option_policy(CLI::MultiOptionPolicy::TakeFirst)` |
| `->join()` | sets `->multi_option_policy(CLI::MultiOptionPolicy::Join)`, which uses newlines to join all arguments into a single string output. |
| `->check(CLI::ExistingFile)`| Requires that the file exists if given.|
| `->check(CLI::ExistingDirectory)`| Requires that the directory exists.|
| `->check(CLI::NonexistentPath)`| Requires that the path does not exist.|
| `->check(CLI::Range(min,max))`| Requires that the option be between min and max (make sure to use floating point if needed). Min defaults to 0.|
| `->each(void(std::string))` | Run a function on each parsed value, *in order*.|
The `->check(...)` modifiers adds a callback function of the form `bool function(std::string)` that runs on every value that the option receives, and returns a value that tells CLI11 whether the check passed or failed.
## Using the `CLI::Option` pointer
Each of the option creation mechanisms returns a pointer to the internally stored option. If you save that pointer, you can continue to access the option, and change setting on it later. The Option object can also be converted to a bool to see if it was passed, or `->count()` can be used to see how many times the option was passed. Since flags are also options, the same methods work on them.
```cpp
CLI::Option* opt = app.add_flag("--opt");
CLI11_PARSE(app, argv, argc);
if(*opt)
std::cout << "Flag recieved " << opt->count() << " times." << std::endl;
```
## Inheritance of defaults
One of CLI11's systems to allow customizability without high levels of verbosity is the inheritance system. You can set default values on the parent `App`, and all options and subcommands created from it remember the default values at the point of creation. The default value for Options, specifically, are accessible through the `option_defaults()` method. There are four settings that can be set and inherited:
* `group`: The group name starts as "Options"
* `required`: If the option must be given. Defaults to `false`. Is ignored for flags.
* `multi_option_policy`: What to do if several copies of an option are passed and one value is expected. Defaults to `CLI::MultiOptionPolicy::Throw`. This is also used for bool flags, but they always are created with the value `CLI::MultiOptionPolicy::TakeLast` regardless of the default, so that multiple bool flags does not cause an error. But you can override that flag by flag.
* `ignore_case`: Allow any mixture of cases for the option or flag name
An example of usage:
```
app.option_defauts()->ignore_case()->group("Required");
app.add_flag("--CaSeLeSs");
app.get_group() // is "Required"
```
Groups are mostly for visual organisation, but an empty string for a group name will hide the option.
## Listing of specialty options:
Besides `add_option` and `add_flag`, there are several special ways to create options for sets and complex numbers.
### Sets
You can add a set with `add_set`, where you give a variable to set and a `std::set` of choices to pick from. There also is a `add_set_ignore_case` version which ignores case when set matching. If you use an existing set instead of an inline one, you can edit the set after adding it and changes will be reflected in the set checking and help message.
```cpp
int val;
app.add_set("--even", val, {0,2,4,6,8});
```
### Complex numbers
You can also add a complex number. This type just needs to support a `(T x, T y)` constructor and be printable. You can also pass one extra argument that will set the label of the type; by default it is "COMPLEX".
```cpp
std::complex<float> val;
app.add_complex("--cplx", val);
```
### Optionals (New in CLI11 1.5)
If you have a compiler with `__has_include`, you can use `std::optional`, `std::experimental::optional`, and `boost::optional` in `add_option`. You can manually enforce support for one of these by defining the corresponding macro before including CLI11 (or in your build system). For example:
```cpp
#define CLI11_BOOST_OPTIONAL
#include <CLI/CLI.hpp>
...
boost::optional<int> x;
app.add_option("-x", x);
CLI11_PARSE(app, argc, argv);
if(x)
std::cout << *x << std::endl;
```
### Windows style options (New in CLI11 1.7)
You can also set the app setting `app->allow_windows_style_options()` to allow windows style options to also be recognized on the command line:
* `/a` (flag)
* `/f filename` (option)
* `/long` (long flag)
* `/file filename` (space)
* `/file:filename` (colon)
Windows style options do not allow combining short options or values not separated from the short option like with `-` options. You still specify option names in the same manor as on Linux with single and double dashes when you use the `add_*` functions, and the Linux style on the command line will still work. If a long and a short option share the same name, the option will match on the first one defined.
[^1]: For example, enums are not printable to `std::cout`.
[^2]: There is a small difference. An combined unlimited option will not prioritize over a positional that could still accept values.

114
book/chapters/subcommands.md Normal file
View File

@@ -0,0 +1,114 @@
# Subcommands and the App
Subcommands are keyword that invoke a new set of options and features. For example, the `git`
command has a long series of subcommands, like `add` and `commit`. Each can have its own options
and implementations. This chapter will focus on implementations that are contained in the same
C++ application, though the system git uses to extend the main command by calling other commands
in separate executables is supported too; that's called "Prefix commands" and is included at the
end of this chapter.
## The parent App
We'll start by discussing the parent `App`. You've already used it quite a bit, to create
options and set option defaults. There are several other things you can do with an `App`, however.
You are given a lot of control the help output. You can set a footer with `app.footer("My Footer")`.
You can replace the default help print when a `ParseError` is thrown with `app.set_failure_message(CLI::FailureMessage::help)`.
The default is `CLI:::FailureMessage::simple`, and you can easily define a new one. Just make a (lambda) function that takes an App pointer
and a reference to an error code (even if you don't use them), and returns a string.
## Adding a subcommand
Subcommands can be added just like an option:
```cpp
CLI::App* sub = app.add_subcommand("sub", "This is a subcommand");
```
The subcommand should have a name as the first argument, and a little description for the
second argument. A pointer to the internally stored subcommand is provided; you usually will
be capturing that pointer and using it later (though you can use callbacks if you prefer). As
always, feel free to use `auto sub = ...` instead of naming the type.
You can check to see if the subcommand was received on the command line several ways:
```cpp
if(*sub) ...
if(sub->parsed()) ...
if(app.got_subcommand(sub)) ...
if(app.got_subcommand("sub")) ...
```
You can also get a list of subcommands with `get_subcommands()`, and they will be in parsing order.
There are a lot of options that you can set on a subcommand; in fact,
subcommands have exactly the same options as your main app, since they are actually
the same class of object (as you may have guessed from the type above). This has the
pleasant side affect of making subcommands infinitely nestable.
## Required subcommands
Each App has controls to set the number of subcommands you expect. This is controlled by:
```cpp
app.require_subcommand(/* min */ 0, /* max */ 1);
```
If you set the max to 0, CLI11 will allow an unlimited number of subcommands. After the (non-unlimited) maximum
is reached, CLI11 will stop trying to match subcommands. So the if you pass "`one two`" to a command, and both `one`
and `two` are subcommands, it will depend on the maximum number as to whether the "`two`" is a subcommand or an argument to the
"`one`" subcommand.
As a shortcut, you can also call the `require_subcommand` method with one argument; that will be the fixed number of subcommands if positive, it
will be the maximum number if negative. Calling it without an argument will set the required subcommands to 1 or more.
The maximum number of subcommands is inherited by subcommands. This allows you to set the maximum to 1 once at the beginning on the parent app if you only want single subcommands throughout your app. You should keep this in mind, if you are dealing with lots of nested subcommands.
## Using callbacks
You've already seen how to check to see what subcommands were given. It's often much easier, however, to just define the code you want to run when you are making your parser, and not run a bunch of code after `CLI11_PARSE` to analyse the state (Procedural! Yuck!). You can do that with lambda functions. A `std::function<void()>` callback `.callback()` is provided, and CLI11 ensures that all options are prepared and usable by reference capture before entering the callback. An
example is shown below in the `geet` program.
## Inheritance of defaults
The following values are inherited when you add a new subcommand. This happens at the point the subcommand is created:
* The name and description for the help flag
* The footer
* The failure message printer function
* Option defaults
* Allow extras
* Prefix command
* Ignore case
* Ignore underscore
* Allow Windows style options
* Fallthrough
* Group name
* Max required subcommands
## Special modes
There are several special modes for Apps and Subcommands.
### Allow extras
Normally CLI11 throws an error if you don't match all items given on the command line. However, you can enable `allow_extras()`
to instead store the extra values in `.remaining()`. You can get all remaining options including those in contained subcommands recursively in the original order with `.remaining(true)`.
`.remaining_size()` is also provided; this counts the size but ignores the `--` special separator if present.
### Fallthrough
Fallthrough allows an option that does not match in a subcommand to "fall through" to the parent command; if that parent
allows that option, it matches there instead. This was added to allow CLI11 to represent models:
```term
gitbook:code $ ./my_program my_model_1 --model_flag --shared_flag
```
Here, `--shared_option` was set on the main app, and on the command line it "falls through" `my_model_1` to match on the main app.
### Prefix command
This is a special mode that allows "prefix" commands, where the parsing completely stops when it gets to an unknown option. Further unknown options are ignored, even if they could match. Git is the traditional example for prefix commands; if you run git with an unknown subcommand, like "`git thing`", it then calls another command called "`git-thing`" with the remaining options intact.

30
book/chapters/toolkits.md Normal file
View File

@@ -0,0 +1,30 @@
# Using CLI11 in a Toolkit
CLI11 was designed to be integrate into a toolkit, providing a native experience for users. This was used in GooFit to provide `GooFit::Application`, an class designed to make ROOT users feel at home.
# Custom namespace
If you want to provide CLI11 in a custom namespace, you'll want to at least put `using CLI::App` in your namespace. You can also include Option, some errors, and validators. You can also put `using namespace CLI` inside your namespace to import everything.
You may also want to make your own copy of the `CLI11_PARSE` macro. Something like:
```cpp
#define MYPACKAGE_PARSE(app, argv, argc) \
try { \
app.parse(argv, argc); \
} catch(const CLI::ParseError &e) { \
return app.exit(e); \
}
```
# Subclassing App
If you subclass `App`, you'll just need to do a few things. You'll need a constructor; calling the base `App` constructor is a good idea, but not necessary (it just sets a description and adds a help flag.
You can call anything you would like to configure in the constructor, like `option_defaults()->take_last()` or `fallthrough()`, and it will be set on all user instances. You can add flags and options, as well.
# Virtual functions provided
You are given a few virtual functions that you can change (only on the main App). `pre_callback` runs right before the callbacks run, letting you print out custom messages at the top of your app.

56
book/chapters/validators.md Normal file
View File

@@ -0,0 +1,56 @@
# Validators
{% hint style='info' %}
Improved in CLI11 1.6
{% endhint %}
There are two forms of validators:
* `transform` validators: mutating
* `check` validators: non-mutating (recommended unless the parsed string must be mutated)
A transform validator comes in one form, a function with the signature `std::string(std::string)`.
The function will take a string and return the modified version of the string. If there is an error,
the function should throw a `CLI::ValidationError` with the appropriate reason as a message.
However, `check` validators come in two forms; either a simple function with the const version of the
above signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This
structure has two members that a user should set; one (`func`) is the function to add to the Option
(exactly matching the above function signature, since it will become that function), and the other is
`tname`, and is the type name to set on the Option (unless empty, in which case the typename will be
left unchanged).
Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them
as if they were a function. In CLI11, const static versions of the validators are provided so that
the user does not have to call a constructor also.
An example of a custom validator:
```cpp
struct LowerCaseValidator : public Validator {
LowerCaseValidator() {
tname = "LOWER";
func = [](const std::string &str) {
if(CLI::detail::to_lower(str) != str)
return std::string("String is not lower case");
else
return std::string();
};
}
};
const static LowerCaseValidator Lowercase;
```
If you were not interested in the extra features of Validator, you could simply pass the lambda function above to the `->check()` method of `Option`.
The built-in validators for CLI11 are:
| Validator | Description |
|---------------------|-------------|
| `ExistingFile` | Check for existing file (returns error message if check fails) |
| `ExistingDirectory` | Check for an existing directory (returns error message if check fails) |
| `ExistingPath` | Check for an existing path |
| `NonexistentPath` | Check for an non-existing path |
| `Range(min=0, max)` | Produce a range (factory). Min and max are inclusive. |

4625
book/code/CLI11.hpp Normal file
View File

File diff suppressed because it is too large Load Diff

38
book/code/CMakeLists.txt Normal file
View File

@@ -0,0 +1,38 @@
cmake_minimum_required(VERSION 3.11)
project(CLI11_Examples LANGUAGES CXX)
# Using CMake 3.11's ability to set imported interface targets
add_library(CLI11::CLI11 IMPORTED INTERFACE)
target_include_directories(CLI11::CLI11 INTERFACE "${CMAKE_CURRENT_SOURCE_DIR}")
target_compile_features(CLI11::CLI11 INTERFACE cxx_std_11)
# Add CTest
enable_testing()
# Quick function to add the base executable
function(add_cli_exe NAME)
add_executable(${NAME} ${NAME}.cpp)
target_link_libraries(${NAME} CLI11::CLI11)
endfunction()
add_cli_exe(simplest)
add_test(NAME simplest COMMAND simplest)
add_cli_exe(intro)
add_test(NAME intro COMMAND intro)
add_test(NAME intro_p COMMAND intro -p 5)
add_cli_exe(flags)
add_test(NAME flags COMMAND flags)
add_test(NAME flags_bip COMMAND flags -b -i -p)
add_cli_exe(geet)
add_test(NAME geet_add COMMAND geet add)
add_test(NAME geet_commit COMMAND geet commit -m "Test")

36
book/code/flags.cpp Normal file
View File

@@ -0,0 +1,36 @@
#include "CLI11.hpp"
#include <iostream>
int main(int argc, char **argv) {
using std::cout;
using std::endl;
CLI::App app{"Flag example program"};
/// [define]
bool flag_bool;
app.add_flag("--bool,-b", flag_bool, "This is a bool flag");
int flag_int;
app.add_flag("-i,--int", flag_int, "This is an int flag");
CLI::Option *flag_plain = app.add_flag("--plain,-p", "This is a plain flag");
/// [define]
/// [parser]
try {
app.parse(argc, argv);
} catch(const CLI::ParseError &e) {
return app.exit(e);
}
/// [parser]
/// [usage]
cout << "The flags program" << endl;
if(flag_bool)
cout << "Bool flag passed" << endl;
if(flag_int > 0)
cout << "Flag int: " << flag_int << endl;
if(*flag_plain)
cout << "Flag plain: " << flag_plain->count() << endl;
/// [usage]
}

50
book/code/geet.cpp Normal file
View File

@@ -0,0 +1,50 @@
#include "CLI11.hpp"
#include <iostream>
int main(int argc, char **argv) {
/// [Intro]
CLI::App app{"Geet, a command line git lookalike that does nothing"};
app.require_subcommand(1);
/// [Intro]
/// [Add]
auto add = app.add_subcommand("add", "Add file(s)");
bool add_update;
add->add_flag("-u,--update", add_update, "Add updated files only");
std::vector<std::string> add_files;
add->add_option("files", add_files, "Files to add");
add->callback([&]() {
std::cout << "Adding:";
if(add_files.empty()) {
if(add_update)
std::cout << " all updated files";
else
std::cout << " all files";
} else {
for(auto file : add_files)
std::cout << " " << file;
}
});
/// [Add]
/// [Commit]
auto commit = app.add_subcommand("commit", "Commit files");
std::string commit_message;
commit->add_option("-m,--message", commit_message, "A message")->required();
commit->callback([&]() { std::cout << "Commit message: " << commit_message; });
/// [Commit]
/// [Parse]
CLI11_PARSE(app, argc, argv);
std::cout << "\nThanks for using geet!\n" << std::endl;
return 0;
/// [Parse]
}

15
book/code/intro.cpp Normal file
View File

@@ -0,0 +1,15 @@
#include "CLI11.hpp"
#include <iostream>
int main(int argc, char **argv) {
CLI::App app{"App description"};
// Define options
int p = 0;
app.add_option("-p", p, "Parameter");
CLI11_PARSE(app, argc, argv);
std::cout << "Parameter value: " << p << std::endl;
return 0;
}

11
book/code/simplest.cpp Normal file
View File

@@ -0,0 +1,11 @@
#include "CLI11.hpp"
int main(int argc, char **argv) {
CLI::App app;
// Add new options/flags here
CLI11_PARSE(app, argc, argv);
return 0;
}

2
docs/mainpage.md
View File

@@ -1,6 +1,6 @@
# Introduction
This is the Doxygen API documentation for CLI11 parser. There is a friendly introduction to CLI11 on the [Github page](https://github.com/CLIUtils/CLI11).
This is the Doxygen API documentation for CLI11 parser. There is a friendly introduction to CLI11 on the [Github page](https://github.com/CLIUtils/CLI11), and [a tutorial series](https://cliutils.github.io/CLI11/book).
The main classes are: