418b7175f5
* add expanded type_size specification * add some more checks for type_size_max * continued work on getting type sizes more flexible * make some more tweaks to option to split up validate and reduce sections * git rid of exceptions on the type_size functions exceptions, allow any number to be entered for the min and max and don't make a distinction between flags and other types. * add expected count * add the allow extra args flag in an option * start working in allow_extra_args * write some stuff in the book, and continue working on the failing test cases * fix a few more of the helpers tests * a few more test cases running * all tests pass, fixing calls in ini files * get vector<pair> working and all tests passing * change callback to use reference to remove allocation and copy operation * add support and test for vector<vector<X>> * change Validators_ to validators_ for consistency * fix linux warnings and errors by reording some templates and adding some typename keywords * add support for std::vector<X> as the cross conversion type so optional<std::vector<X>> is supported using the full template of add_option. * a few more test cases to take care of some coverage gaps * add missing parenthesis * add some more tests for coverage gaps * add test for flag like option * add transform test for `as<X>` function and make it pass through the defaults * add a few more tests and have vector default string interpreted correctly. * add test for defaulted integer, and route default string for defaulted value which would otherwise be empty * some code cleanup and comments and few more test coverage gap tests * add more tests and fix a few bugs on the type size and different code paths * remove path in results by fixing the clear of options so they go back to parsing state. * get coverage back to 100% * clang_tidy, and codacy fixes * reorder the lexical_conversion definitions * update some formatting * update whitespace on book chapter
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, this tutorial book, and more technical API docs.
Feel free to contribute to this documentation here 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:
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:
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:
gitbook:examples $ c++ -std=c++11 intro.cpp
Much more complicated options are handled elegantly:
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. 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.