0f5bf21e91
This adds a round trip test for config file generation to the fuzzer. (the next step after this PR will be a fuzzer that verifies that the round trip actually matches the results. This change ended up requiring quite a few minor changes to fix the ambiguities between the config file generation and config file reader. 1). There was a number of potential conflicts between positional names and regular option names that could be triggered in config files, this required a number of additional checks on the positional naming to ensure no conflicts. 2). flag options with disable flag override can produce output results that are not valid by themselves, resolving this required flag input to be able to handle an array and output the original value set of results. 3). strings with non-printable characters could cause all sorts of chaos in the config files. This was resolved by generating a binary string conversion format and handling multiline comments and characters, and handling escaped characters. Note; I think a better solution is to move to fully supporting string formatting and escaping along with the binary strings from TOML now that TOML 1.0 is finalized. That will not be this PR though, maybe the next one. 4). Lot of ambiguities and edge cases in the string splitter, this was reworked 5). handling of comments was not done well, especially comment characters in the name of the option which is allowed. 6). non printable characters in the option naming. This would be weird in practice but it also cause some big holes in the config file generation, so the restricted character set for option naming was expanded. (don't allow spaces or control characters). --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
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 0:
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 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.