1# CLI11: Command line parser for C++11 2 3 4 5[![Build Status Azure][azure-badge]][azure] 6[![Actions Status][actions-badge]][actions-link] 7[![Build Status AppVeyor][appveyor-badge]][appveyor] 8[![Code Coverage][codecov-badge]][codecov] 9[![Codacy Badge][codacy-badge]][codacy-link] 10[![License: BSD][license-badge]](./LICENSE) 11[![DOI][doi-badge]][doi-link] 12 13[![Gitter chat][gitter-badge]][gitter] 14[![Latest GHA release][releases-badge]][github releases] 15[![Latest release][repology-badge]][repology] 16[![Conan.io][conan-badge]][conan-link] 17[![Conda Version][conda-badge]][conda-link] 18[![Try CLI11 2.1 online][wandbox-badge]][wandbox-link] 19 20[What's new](./CHANGELOG.md) • 21[Documentation][gitbook] • 22[API Reference][api-docs] 23 24CLI11 is a command line parser for C++11 and beyond that provides a rich feature set with a simple and intuitive interface. 25 26## Table of Contents 27 28* [Background](#background) 29 * [Introduction](#introduction) 30 * [Why write another CLI parser?](#why-write-another-cli-parser) 31 * [Other parsers](#other-parsers) 32 * [Features not supported by this library](#features-not-supported-by-this-library) 33* [Install](#install) 34* [Usage](#usage) 35 * [Adding options](#adding-options) 36 * [Option types](#option-types) 37 * [Example](#example) 38 * [Option options](#option-options) 39 * [Validators](#validators) 40 * [Transforming Validators](#transforming-validators) 41 * [Validator operations](#validator-operations) 42 * [Custom Validators](#custom-validators) 43 * [Querying Validators](#querying-validators) 44 * [Getting Results](#getting-results) 45 * [Subcommands](#subcommands) 46 * [Subcommand options](#subcommand-options) 47 * [Option groups](#option-groups) 48 * [Callbacks](#callbacks) 49 * [Configuration file](#configuration-file) 50 * [Inheriting defaults](#inheriting-defaults) 51 * [Formatting](#formatting) 52 * [Subclassing](#subclassing) 53 * [How it works](#how-it-works) 54 * [Utilities](#utilities) 55 * [Other libraries](#other-libraries) 56* [API](#api) 57* [Examples](#Examples) 58* [Contribute](#contribute) 59* [License](#license) 60 61Features that were added in the last released major version are marked with "��". Features only available in main are marked with "��". 62 63## Background 64 65### Introduction 66 67CLI11 provides all the features you expect in a powerful command line parser, with a beautiful, minimal syntax and no dependencies beyond C++11. It is header only, and comes in a single file form for easy inclusion in projects. It is easy to use for small projects, but powerful enough for complex command line projects, and can be customized for frameworks. 68It is tested on [Azure][] and [GitHub Actions][actions-link], and was originally used by the [GooFit GPU fitting framework][goofit]. It was inspired by [`plumbum.cli`][plumbum] for Python. CLI11 has a user friendly introduction in this README, a more in-depth tutorial [GitBook][], as well as [API documentation][api-docs] generated by Travis. 69See the [changelog](./CHANGELOG.md) or [GitHub Releases][] for details for current and past releases. Also see the [Version 1.0 post][], [Version 1.3 post][], [Version 1.6 post][], or [Version 2.0 post][] for more information. 70 71You can be notified when new releases are made by subscribing to <https://github.com/CLIUtils/CLI11/releases.atom> on an RSS reader, like Feedly, or use the releases mode of the GitHub watching tool. 72 73### Why write another CLI parser? 74 75An acceptable CLI parser library should be all of the following: 76 77* Easy to include (i.e., header only, one file if possible, **no external requirements**). 78* Short, simple syntax: This is one of the main reasons to use a CLI parser, it should make variables from the command line nearly as easy to define as any other variables. If most of your program is hidden in CLI parsing, this is a problem for readability. 79* C++11 or better: Should work with GCC 4.8+ (default on CentOS/RHEL 7), Clang 3.4+, AppleClang 7+, NVCC 7.0+, or MSVC 2015+. 80* Work on Linux, macOS, and Windows. 81* Well tested on all common platforms and compilers. "Well" is defined as having good coverage measured by [CodeCov][]. 82* Clear help printing. 83* Nice error messages. 84* Standard shell idioms supported naturally, like grouping flags, a positional separator, etc. 85* Easy to execute, with help, parse errors, etc. providing correct exit and details. 86* Easy to extend as part of a framework that provides "applications" to users. 87* Usable subcommand syntax, with support for multiple subcommands, nested subcommands, option groups, and optional fallthrough (explained later). 88* Ability to add a configuration file (`TOML`, `INI`, or custom format), and produce it as well. 89* Produce real values that can be used directly in code, not something you have pay compute time to look up, for HPC applications. 90* Work with standard types, simple custom types, and extensible to exotic types. 91* Permissively licensed. 92 93### Other parsers 94 95<details><summary>The major CLI parsers for C++ include, with my biased opinions: (click to expand)</summary><p> 96 97| Library | My biased opinion | 98| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | 99| [Boost Program Options][] | A great library if you already depend on Boost, but its pre-C++11 syntax is really odd and setting up the correct call in the main function is poorly documented (and is nearly a page of code). A simple wrapper for the Boost library was originally developed, but was discarded as CLI11 became more powerful. The idea of capturing a value and setting it originated with Boost PO. [See this comparison.][cli11-po-compare] | 100| [The Lean Mean C++ Option Parser][] | One header file is great, but the syntax is atrocious, in my opinion. It was quite impractical to wrap the syntax or to use in a complex project. It seems to handle standard parsing quite well. | 101| [TCLAP][] | The not-quite-standard command line parsing causes common shortcuts to fail. It also seems to be poorly supported, with only minimal bugfixes accepted. Header only, but in quite a few files. Has not managed to get enough support to move to GitHub yet. No subcommands. Produces wrapped values. | 102| [Cxxopts][] | C++11, single file, and nice CMake support, but requires regex, therefore GCC 4.8 (CentOS 7 default) does not work. Syntax closely based on Boost PO, so not ideal but familiar. | 103| [DocOpt][] | Completely different approach to program options in C++11, you write the docs and the interface is generated. Too fragile and specialized. | 104 105After I wrote this, I also found the following libraries: 106 107| Library | My biased opinion | 108| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | 109| [GFlags][] | The Google Commandline Flags library. Uses macros heavily, and is limited in scope, missing things like subcommands. It provides a simple syntax and supports config files/env vars. | 110| [GetOpt][] | Very limited C solution with long, convoluted syntax. Does not support much of anything, like help generation. Always available on UNIX, though (but in different flavors). | 111| [ProgramOptions.hxx][] | Interesting library, less powerful and no subcommands. Nice callback system. | 112| [Args][] | Also interesting, and supports subcommands. I like the optional-like design, but CLI11 is cleaner and provides direct value access, and is less verbose. | 113| [Argument Aggregator][] | I'm a big fan of the [fmt][] library, and the try-catch statement looks familiar. :thumbsup: Doesn't seem to support subcommands. | 114| [Clara][] | Simple library built for the excellent [Catch][] testing framework. Unique syntax, limited scope. | 115| [Argh!][] | Very minimalistic C++11 parser, single header. Don't have many features. No help generation?!?! At least it's exception-free. | 116| [CLI][] | Custom language and parser. Huge build-system overkill for very little benefit. Last release in 2009, but still occasionally active. | 117| [argparse][] | C++17 single file argument parser. Design seems similar to CLI11 in some ways. The author has several other interesting projects. | 118 119See [Awesome C++][] for a less-biased list of parsers. You can also find other single file libraries at [Single file libs][]. 120 121</p></details> 122<br/> 123 124None of these libraries fulfill all the above requirements, or really even come close. As you probably have already guessed, CLI11 does. 125So, this library was designed to provide a great syntax, good compiler compatibility, and minimal installation fuss. 126 127### Features not supported by this library 128 129There are some other possible "features" that are intentionally not supported by this library: 130 131* Non-standard variations on syntax, like `-long` options. This is non-standard and should be avoided, so that is enforced by this library. 132* Completion of partial options, such as Python's `argparse` supplies for incomplete arguments. It's better not to guess. Most third party command line parsers for python actually reimplement command line parsing rather than using argparse because of this perceived design flaw (recent versions do have an option to disable it). 133* Autocomplete: This might eventually be added to both Plumbum and CLI11, but it is not supported yet. 134* Wide strings / unicode: Since this uses the standard library only, it might be hard to properly implement, but I would be open to suggestions in how to do this. 135 136## Install 137 138To use, there are several methods: 139 140* All-in-one local header: Copy `CLI11.hpp` from the [most recent release][github releases] into your include directory, and you are set. This is combined from the source files for every release. This includes the entire command parser library, but does not include separate utilities (like `Timer`, `AutoTimer`). The utilities are completely self contained and can be copied separately. 141* All-in-one global header: Like above, but copying the file to a shared folder location like `/opt/CLI11`. Then, the C++ include path has to be extended to point at this folder. With CMake, use `include_directories(/opt/CLI11)` 142* Local headers and target: Use `CLI/*.hpp` files. You could check out the repository as a git submodule, for example. With CMake, you can use `add_subdirectory` and the `CLI11::CLI11` interface target when linking. If not using a submodule, you must ensure that the copied files are located inside the same tree directory than your current project, to prevent an error with CMake and `add_subdirectory`. 143* Global headers: Use `CLI/*.hpp` files stored in a shared folder. You could check out the git repository to a system-wide folder, for example `/opt/`. With CMake, you could add to the include path via: 144 145```bash 146if(NOT DEFINED CLI11_DIR) 147set (CLI11_DIR "/opt/CLI11" CACHE STRING "CLI11 git repository") 148endif() 149include_directories(${CLI11_DIR}/include) 150``` 151 152And then in the source code (adding several headers might be needed to prevent linker errors): 153 154```cpp 155#include "CLI/App.hpp" 156#include "CLI/Formatter.hpp" 157#include "CLI/Config.hpp" 158``` 159 160* Global headers and target: configuring and installing the project is required for linking CLI11 to your project in the same way as you would do with any other external library. With CMake, this step allows using `find_package(CLI11 CONFIG REQUIRED)` and then using the `CLI11::CLI11` target when linking. If `CMAKE_INSTALL_PREFIX` was changed during install to a specific folder like `/opt/CLI11`, then you have to pass `-DCLI11_DIR=/opt/CLI11` when building your current project. You can also use [Conan.io][conan-link] or [Hunter][]. 161 (These are just conveniences to allow you to use your favorite method of managing packages; it's just header only so including the correct path and 162 using C++11 is all you really need.) 163* Via FetchContent in CMake 3.14+ (or 3.11+ with more work): you can add this with fetch-content, then use the `CLI11::CLI11` target as above, and CMake will download the project in the configure stage: 164 165```cmake 166include(FetchContent) 167FetchContent_Declare( 168 cli11 169 GIT_REPOSITORY https://github.com/CLIUtils/CLI11 170 GIT_TAG v2.1.2 171) 172 173FetchContent_MakeAvailable(cli11) 174``` 175 176It is highly recommended that you use the git hash for `GIT_TAG` instead of a tag or branch, as that will both be more secure, as well as faster to reconfigure - CMake will not have to reach out to the internet to see if the tag moved. You can also download just the single header file from the releases using `file(DOWNLOAD`. 177 178To build the tests, checkout the repository and use CMake: 179 180```bash 181cmake -S . -B build 182cmake --build build 183CTEST_OUTPUT_ON_FAILURE=1 cmake --build build -t test 184``` 185 186<details><summary>Note: Special instructions for GCC 8</summary><p> 187 188If you are using GCC 8 and using it in C++17 mode with CLI11. CLI11 makes use of the `<filesystem>` header if available, but specifically for this compiler, the `filesystem` library is separate from the standard library and needs to be linked separately. So it is available but CLI11 doesn't use it by default. 189 190Specifically `libstdc++fs` needs to be added to the linking list and `CLI11_HAS_FILESYSTEM=1` has to be defined. Then the filesystem variant of the Validators could be used on GCC 8. GCC 9+ does not have this issue so the `<filesystem>` is used by default. 191 192There may also be other cases where a specific library needs to be linked. 193 194Defining `CLI11_HAS_FILESYSTEM=0` which will remove the usage and hence any linking issue. 195 196In some cases certain clang compilations may require linking against `libc++fs`. These situations have not been encountered so the specific situations requiring them are unknown yet. 197 198</p></details> 199</br> 200 201## Usage 202 203### Adding options 204 205To set up, add options, and run, your main function will look something like this: 206 207```cpp 208int main(int argc, char** argv) { 209 CLI::App app{"App description"}; 210 211 std::string filename = "default"; 212 app.add_option("-f,--file", filename, "A help string"); 213 214 CLI11_PARSE(app, argc, argv); 215 return 0; 216} 217``` 218 219<details><summary>Note: If you don't like macros, this is what that macro expands to: (click to expand)</summary><p> 220 221```cpp 222try { 223 app.parse(argc, argv); 224} catch (const CLI::ParseError &e) { 225 return app.exit(e); 226} 227``` 228 229The try/catch block ensures that `-h,--help` or a parse error will exit with the correct return code (selected from `CLI::ExitCodes`). (The return here should be inside `main`). You should not assume that the option values have been set inside the catch block; for example, help flags intentionally short-circuit all other processing for speed and to ensure required options and the like do not interfere. 230 231</p></details> 232</br> 233 234The initialization is just one line, adding options is just two each. The parse macro is just one line (or 5 for the contents of the macro). After the app runs, the filename will be set to the correct value if it was passed, otherwise it will be set to the default. You can check to see if this was passed on the command line with `app.count("--file")`. 235 236#### Option types 237 238While all options internally are the same type, there are several ways to add an option depending on what you need. The supported values are: 239 240```cpp 241// Add options 242app.add_option(option_name, help_str="") 243 244app.add_option(option_name, 245 variable_to_bind_to, // bool, char(see note), int, float, vector, enum, std::atomic, or string-like, or anything with a defined conversion from a string or that takes an int, double, or string in a constructor. Also allowed are tuples, std::array or std::pair. Also supported are complex numbers, wrapper types, and containers besides vectorof any other supported type. 246 help_string="") 247 248app.add_option_function<type>(option_name, 249 function <void(const type &value)>, // type can be any type supported by add_option 250 help_string="") 251 252// char as an option type is supported before 2.0 but in 2.0 it defaulted to allowing single non numerical characters in addition to the numeric values. 253 254// There is a template overload which takes two template parameters the first is the type of object to assign the value to, the second is the conversion type. The conversion type should have a known way to convert from a string, such as any of the types that work in the non-template version. If XC is a std::pair and T is some non pair type. Then a two argument constructor for T is called to assign the value. For tuples or other multi element types, XC must be a single type or a tuple like object of the same size as the assignment type 255app.add_option<typename T, typename XC>(option_name, 256 T &output, // output must be assignable or constructible from a value of type XC 257 help_string="") 258 259// Add flags 260app.add_flag(option_name, 261 help_string="") 262 263app.add_flag(option_name, 264 variable_to_bind_to, // bool, int, float, complex, containers, enum, std::atomic, or string-like, or any singular object with a defined conversion from a string like add_option 265 help_string="") 266 267app.add_flag_function(option_name, 268 function <void(std::int64_t count)>, 269 help_string="") 270 271app.add_flag_callback(option_name,function<void(void)>,help_string="") 272 273// Add subcommands 274App* subcom = app.add_subcommand(name, description); 275 276Option_group *app.add_option_group(name,description); 277``` 278 279An option name may start with any character except ('-', ' ', '\n', and '!') ��. For long options, after the first character all characters are allowed except ('=',':','{',' ', '\n')��. For the `add_flag*` functions '{' and '!' have special meaning which is why they are not allowed. Names are given as a comma separated string, with the dash or dashes. An option or flag can have as many names as you want, and afterward, using `count`, you can use any of the names, with dashes as needed, to count the options. One of the names is allowed to be given without proceeding dash(es); if present the option is a positional option, and that name will be used on the help line for its positional form. 280 281The `add_option_function<type>(...` function will typically require the template parameter be given unless a `std::function` object with an exact match is passed. The type can be any type supported by the `add_option` function. The function should throw an error (`CLI::ConversionError` or `CLI::ValidationError` possibly) if the value is not valid. 282 283The two parameter template overload can be used in cases where you want to restrict the input such as 284 285```cpp 286double val 287app.add_option<double,unsigned int>("-v",val); 288``` 289 290which would first verify the input is convertible to an `unsigned int` before assigning it. Or using some variant type 291 292```cpp 293using vtype=std::variant<int, double, std::string>; 294 vtype v1; 295app.add_option<vtype,std:string>("--vs",v1); 296app.add_option<vtype,int>("--vi",v1); 297app.add_option<vtype,double>("--vf",v1); 298``` 299 300otherwise the output would default to a string. The `add_option` can be used with any integral or floating point types, enumerations, or strings. Or any type that takes an int, double, or std\::string in an assignment operator or constructor. If an object can take multiple varieties of those, std::string takes precedence, then double then int. To better control which one is used or to use another type for the underlying conversions use the two parameter template to directly specify the conversion type. 301 302Types such as (std or boost) `optional<int>`, `optional<double>`, and `optional<string>` and any other wrapper types are supported directly. For purposes of CLI11 wrapper types are those which `value_type` definition. See [CLI11 Advanced Topics/Custom Converters][] for information on how you can add your own converters for additional types. 303 304Vector types can also be used in the two parameter template overload 305 306```cpp 307std::vector<double> v1; 308app.add_option<std::vector<double>,int>("--vs",v1); 309``` 310 311would load a vector of doubles but ensure all values can be represented as integers. 312 313Automatic direct capture of the default string is disabled when using the two parameter template. Use `set_default_str(...)` or `->default_function(std::string())` to set the default string or capture function directly for these cases. 314 315Flag options specified through the `add_flag*` functions allow a syntax for the option names to default particular options to a false value or any other value if some flags are passed. For example: 316 317```cpp 318app.add_flag("--flag,!--no-flag",result,"help for flag"); 319``` 320 321specifies that if `--flag` is passed on the command line result will be true or contain a value of 1. If `--no-flag` is 322passed `result` will contain false or -1 if `result` is a signed integer type, or 0 if it is an unsigned type. An 323alternative form of the syntax is more explicit: `"--flag,--no-flag{false}"`; this is equivalent to the previous 324example. This also works for short form options `"-f,!-n"` or `"-f,-n{false}"`. If `variable_to_bind_to` is anything but an integer value the 325default behavior is to take the last value given, while if `variable_to_bind_to` is an integer type the behavior will be to sum 326all the given arguments and return the result. This can be modified if needed by changing the `multi_option_policy` on each flag (this is not inherited). 327The default value can be any value. For example if you wished to define a numerical flag: 328 329```cpp 330app.add_flag("-1{1},-2{2},-3{3}",result,"numerical flag") 331``` 332 333Using any of those flags on the command line will result in the specified number in the output. Similar things can be done for string values, and enumerations, as long as the default value can be converted to the given type. 334 335On a `C++14` compiler, you can pass a callback function directly to `.add_flag`, while in C++11 mode you'll need to use `.add_flag_function` if you want a callback function. The function will be given the number of times the flag was passed. You can throw a relevant `CLI::ParseError` to signal a failure. 336 337#### Example 338 339* `"one,-o,--one"`: Valid as long as not a flag, would create an option that can be specified positionally, or with `-o` or `--one` 340* `"this"` Can only be passed positionally 341* `"-a,-b,-c"` No limit to the number of non-positional option names 342 343The add commands return a pointer to an internally stored `Option`. 344This option can be used directly to check for the count (`->count()`) after parsing to avoid a string based lookup. 345 346#### Option options 347 348Before parsing, you can set the following options: 349 350* `->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. 351* `->expected(N)`: Take `N` values instead of as many as possible, only for vector args. If negative, require at least `-N`; end with `--` or another recognized option or subcommand. 352* `->expected(MIN,MAX)`: Set a range of expected values to accompany an option. `expected(0,1)` is the equivalent of making a flag. 353* `->type_name(typename)`: Set the name of an Option's type (`type_name_fn` allows a function instead) 354* `->type_size(N)`: Set the intrinsic size of an option value. The parser will require multiples of this number if negative. Most of the time this is detected automatically though can be modified for specific use cases. 355* `->type_size(MIN,MAX)`: Set the intrinsic size of an option to a range. 356* `->needs(opt)`: This option requires another option to also be present, opt is an `Option` pointer. Options can be removed from the `needs` with `remove_needs(opt)`. The option can also be specified with a string containing the name of the option 357* `->excludes(opt)`: This option cannot be given with `opt` present, opt is an `Option` pointer. Can also be given as a string containing the name of the option. Options can be removed from the excludes list with `->remove_excludes(opt)` 358* `->envname(name)`: Gets the value from the environment if present and not passed on the command line. 359* `->group(name)`: The help group to put the option in. No effect for positional options. Defaults to `"Options"`. `""` will not show up in the help print (hidden). 360* `->ignore_case()`: Ignore the case on the command line (also works on subcommands, does not affect arguments). 361* `->ignore_underscore()`: Ignore any underscores in the options names (also works on subcommands, does not affect arguments). For example "option_one" will match with "optionone". This does not apply to short form options since they only have one character 362* `->disable_flag_override()`: From the command line long form flag options can be assigned a value on the command line using the `=` notation `--flag=value`. If this behavior is not desired, the `disable_flag_override()` disables it and will generate an exception if it is done on the command line. The `=` does not work with short form flag options. 363* `->allow_extra_args(true/false)`: If set to true the option will take an unlimited number of arguments like a vector, if false it will limit the number of arguments to the size of the type used in the option. Default value depends on the nature of the type use, containers default to true, others default to false. 364* `->delimiter(char)`: Allows specification of a custom delimiter for separating single arguments into vector arguments, for example specifying `->delimiter(',')` on an option would result in `--opt=1,2,3` producing 3 elements of a vector and the equivalent of --opt 1 2 3 assuming opt is a vector value. 365* `->description(str)`: Set/change the description. 366* `->multi_option_policy(CLI::MultiOptionPolicy::Throw)`: Set the multi-option policy. Shortcuts available: `->take_last()`, `->take_first()`,`->take_all()`, and `->join()`. This will only affect options expecting 1 argument or bool flags (which do not inherit their default but always start with a specific policy). `->join(delim)` can also be used to join with a specific delimiter. This equivalent to calling `->delimiter(delim)` and `->join()` 367* `->check(std::string(const std::string &), validator_name="",validator_description="")`: Define a check function. The function should return a non empty string with the error message if the check fails 368* `->check(Validator)`: Use a Validator object to do the check see [Validators](#validators) for a description of available Validators and how to create new ones. 369* `->transform(std::string(std::string &), validator_name="",validator_description=")`: Converts the input string into the output string, in-place in the parsed options. 370* `->transform(Validator)`: Uses a Validator object to do the transformation see [Validators](#validators) for a description of available Validators and how to create new ones. 371* `->each(void(const std::string &)>`: Run this function on each value received, as it is received. It should throw a `ValidationError` if an error is encountered. 372* `->configurable(false)`: Disable this option from being in a configuration file. 373* `->capture_default_str()`: Store the current value attached and display it in the help string. 374* `->default_function(std::string())`: Advanced: Change the function that `capture_default_str()` uses. 375* `->always_capture_default()`: Always run `capture_default_str()` when creating new options. Only useful on an App's `option_defaults`. 376* `->default_str(string)`: Set the default string directly (NO VALIDATION OR CALLBACKS). This string will also be used as a default value if no arguments are passed and the value is requested. 377* `->default_val(value)`: Generate the default string from a value and validate that the value is also valid. For options that assign directly to a value type the value in that type is also updated. Value must be convertible to a string(one of known types or have a stream operator). The callback may be triggered if the `run_callback_for_default` is set. 378* `->run_callback_for_default()`: This will force the option callback to be executed or the variable set when the `default_val` is set. 379* `->option_text(string)`: Sets the text between the option name and description. 380* `->force_callback()`: �� Causes the option callback or value set to be triggered even if the option was not present in parsing. 381* `->trigger_on_parse()`: �� If set, causes the callback and all associated validation checks for the option to be executed when the option value is parsed vs. at the end of all parsing. This could cause the callback to be executed multiple times. 382 383These options return the `Option` pointer, so you can chain them together, and even skip storing the pointer entirely. The `each` function takes any function that has the signature `void(const std::string&)`; it should throw a `ValidationError` when validation fails. The help message will have the name of the parent option prepended. Since `each`, `check` and `transform` use the same underlying mechanism, you can chain as many as you want, and they will be executed in order. Operations added through `transform` are executed first in reverse order of addition, and `check` and `each` are run following the transform functions in order of addition. If you just want to see the unconverted values, use `.results()` to get the `std::vector<std::string>` of results. 384 385On the command line, options can be given as: 386 387* `-a` (flag) 388* `-abc` (flags can be combined) 389* `-f filename` (option) 390* `-ffilename` (no space required) 391* `-abcf filename` (flags and option can be combined) 392* `--long` (long flag) 393* `--long_flag=true` (long flag with equals to override default value) 394* `--file filename` (space) 395* `--file=filename` (equals) 396 397If `allow_windows_style_options()` is specified in the application or subcommand options can also be given as: 398 399* `/a` (flag) 400* `/f filename` (option) 401* `/long` (long flag) 402* `/file filename` (space) 403* `/file:filename` (colon) 404* `/long_flag:false` (long flag with : to override the default value) 405 * Windows style options do not allow combining short options or values not separated from the short option like with `-` options 406 407Long flag options may be given with an `=<value>` to allow specifying a false value, or some other value to the flag. See [config files](#configuration-file) for details on the values supported. NOTE: only the `=` or `:` for windows-style options may be used for this, using a space will result in the argument being interpreted as a positional argument. This syntax can override the default values, and can be disabled by using `disable_flag_override()`. 408 409Extra positional arguments will cause the program to exit, so at least one positional option with a vector is recommended if you want to allow extraneous arguments. 410If you set `.allow_extras()` on the main `App`, you will not get an error. You can access the missing options using `remaining` (if you have subcommands, `app.remaining(true)` will get all remaining options, subcommands included). 411If the remaining arguments are to processed by another `App` then the function `remaining_for_passthrough()` can be used to get the remaining arguments in reverse order such that `app.parse(vector)` works directly and could even be used inside a subcommand callback. 412 413You can access a vector of pointers to the parsed options in the original order using `parse_order()`. 414If `--` is present in the command line that does not end an unlimited option, then 415everything after that is positional only. 416 417#### Validators 418Validators are structures to check or modify inputs, they can be used to verify that an input meets certain criteria or transform it into another value. They are added through the `check` or `transform` functions. The differences between the two function are that checks do not modify the input whereas transforms can and are executed before any Validators added through `check`. 419 420CLI11 has several Validators built-in that perform some common checks 421 422* `CLI::IsMember(...)`: Require an option be a member of a given set. See [Transforming Validators](#transforming-validators) for more details. 423* `CLI::Transformer(...)`: Modify the input using a map. See [Transforming Validators](#transforming-validators) for more details. 424* `CLI::CheckedTransformer(...)`: Modify the input using a map, and require that the input is either in the set or already one of the outputs of the set. See [Transforming Validators](#transforming-validators) for more details. 425* `CLI::AsNumberWithUnit(...)`: Modify the `<NUMBER> <UNIT>` pair by matching the unit and multiplying the number by the corresponding factor. It can be used as a base for transformers, that accept things like size values (`1 KB`) or durations (`0.33 ms`). 426* `CLI::AsSizeValue(...)`: Convert inputs like `100b`, `42 KB`, `101 Mb`, `11 Mib` to absolute values. `KB` can be configured to be interpreted as 10^3 or 2^10. 427* `CLI::ExistingFile`: Requires that the file exists if given. 428* `CLI::ExistingDirectory`: Requires that the directory exists. 429* `CLI::ExistingPath`: Requires that the path (file or directory) exists. 430* `CLI::NonexistentPath`: Requires that the path does not exist. 431* `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. 432* `CLI::Bounded(min,max)`: Modify the input such that it is always between min and max (make sure to use floating point if needed). Min defaults to 0. Will produce an error if conversion is not possible. 433* `CLI::PositiveNumber`: Requires the number be greater than 0 434* `CLI::NonNegativeNumber`: Requires the number be greater or equal to 0 435* `CLI::Number`: Requires the input be a number. 436* `CLI::ValidIPV4`: Requires that the option be a valid IPv4 string e.g. `'255.255.255.255'`, `'10.1.1.7'`. 437* `CLI::TypeValidator<TYPE>`:Requires that the option be convertible to the specified type e.g. `CLI::TypeValidator<unsigned int>()` would require that the input be convertible to an `unsigned int` regardless of the end conversion. 438 439These Validators can be used by simply passing the name into the `check` or `transform` methods on an option 440 441```cpp 442->check(CLI::ExistingFile); 443->check(CLI::Range(0,10)); 444``` 445 446Validators can be merged using `&` and `|` and inverted using `!`. For example: 447 448```cpp 449->check(CLI::Range(0,10)|CLI::Range(20,30)); 450``` 451 452will produce a check to ensure a value is between 0 and 10 or 20 and 30. 453 454```cpp 455->check(!CLI::PositiveNumber); 456``` 457 458will produce a check for a number less than or equal to 0. 459 460##### Transforming Validators 461 462There are a few built in Validators that let you transform values if used with the `transform` function. If they also do some checks then they can be used `check` but some may do nothing in that case. 463 464* `CLI::Bounded(min,max)` will bound values between min and max and values outside of that range are limited to min or max, it will fail if the value cannot be converted and produce a `ValidationError` 465* The `IsMember` Validator lets you specify a set of predefined options. You can pass any container or copyable pointer (including `std::shared_ptr`) to a container to this Validator; the container just needs to be iterable and have a `::value_type`. The key type should be convertible from a string, You can use an initializer list directly if you like. If you need to modify the set later, the pointer form lets you do that; the type message and check will correctly refer to the current version of the set. The container passed in can be a set, vector, or a map like structure. If used in the `transform` method the output value will be the matching key as it could be modified by filters. 466 467After specifying a set of options, you can also specify "filter" functions of the form `T(T)`, where `T` is the type of the values. The most common choices probably will be `CLI::ignore_case` an `CLI::ignore_underscore`, and `CLI::ignore_space`. These all work on strings but it is possible to define functions that work on other types. Here are some examples of `IsMember`: 468 469* `CLI::IsMember({"choice1", "choice2"})`: Select from exact match to choices. 470* `CLI::IsMember({"choice1", "choice2"}, CLI::ignore_case, CLI::ignore_underscore)`: Match things like `Choice_1`, too. 471* `CLI::IsMember(std::set<int>({2,3,4}))`: Most containers and types work; you just need `std::begin`, `std::end`, and `::value_type`. 472* `CLI::IsMember(std::map<std::string, TYPE>({{"one", 1}, {"two", 2}}))`: You can use maps; in `->transform()` these replace the matched value with the matched key. The value member of the map is not used in `IsMember`, so it can be any type. 473* `auto p = std::make_shared<std::vector<std::string>>(std::initializer_list<std::string>("one", "two")); CLI::IsMember(p)`: You can modify `p` later. 474* The `Transformer` and `CheckedTransformer` Validators transform one value into another. Any container or copyable pointer (including `std::shared_ptr`) to a container that generates pairs of values can be passed to these `Validator's`; the container just needs to be iterable and have a `::value_type` that consists of pairs. The key type should be convertible from a string, and the value type should be convertible to a string You can use an initializer list directly if you like. If you need to modify the map later, the pointer form lets you do that; the description message will correctly refer to the current version of the map. `Transformer` does not do any checking so values not in the map are ignored. `CheckedTransformer` takes an extra step of verifying that the value is either one of the map key values, in which case it is transformed, or one of the expected output values, and if not will generate a `ValidationError`. A Transformer placed using `check` will not do anything. 475 476After specifying a map of options, you can also specify "filter" just like in `CLI::IsMember`. 477Here are some examples (`Transformer` and `CheckedTransformer` are interchangeable in the examples) 478of `Transformer`: 479 480* `CLI::Transformer({{"key1", "map1"},{"key2","map2"}})`: Select from key values and produce map values. 481* `CLI::Transformer(std::map<std::string,int>({"two",2},{"three",3},{"four",4}}))`: most maplike containers work, the `::value_type` needs to produce a pair of some kind. 482* `CLI::CheckedTransformer(std::map<std::string, int>({{"one", 1}, {"two", 2}}))`: You can use maps; in `->transform()` these replace the matched key with the value. `CheckedTransformer` also requires that the value either match one of the keys or match one of known outputs. 483* `auto p = std::make_shared<CLI::TransformPairs<std::string>>(std::initializer_list<std::pair<std::string,std::string>>({"key1", "map1"},{"key2","map2"})); CLI::Transformer(p)`: You can modify `p` later. `TransformPairs<T>` is an alias for `std::vector<std::pair<<std::string,T>>` 484 485NOTES: If the container used in `IsMember`, `Transformer`, or `CheckedTransformer` has a `find` function like `std::unordered_map` or `std::map` then that function is used to do the searching. If it does not have a `find` function a linear search is performed. If there are filters present, the fast search is performed first, and if that fails a linear search with the filters on the key values is performed. 486 487##### Validator operations 488 489Validators are copyable and have a few operations that can be performed on them to alter settings. Most of the built in Validators have a default description that is displayed in the help. This can be altered via `.description(validator_description)`. 490The name of a Validator, which is useful for later reference from the `get_validator(name)` method of an `Option` can be set via `.name(validator_name)` 491The operation function of a Validator can be set via 492`.operation(std::function<std::string(std::string &>)`. The `.active()` function can activate or deactivate a Validator from the operation. A validator can be set to apply only to a specific element of the output. For example in a pair option `std::pair<int, std::string>` the first element may need to be a positive integer while the second may need to be a valid file. The `.application_index(int)` function can specify this. It is zero based and negative indices apply to all values. 493 494```cpp 495opt->check(CLI::Validator(CLI::PositiveNumber).application_index(0)); 496opt->check(CLI::Validator(CLI::ExistingFile).application_index(1)); 497``` 498 499All the validator operation functions return a Validator reference allowing them to be chained. For example 500 501```cpp 502opt->check(CLI::Range(10,20).description("range is limited to sensible values").active(false).name("range")); 503``` 504 505will specify a check on an option with a name "range", but deactivate it for the time being. 506The check can later be activated through 507 508```cpp 509opt->get_validator("range")->active(); 510``` 511 512##### Custom Validators 513 514A validator object with a custom function can be created via 515 516```cpp 517CLI::Validator(std::function<std::string(std::string &)>,validator_description,validator_name=""); 518``` 519 520or if the operation function is set later they can be created with 521 522```cpp 523CLI::Validator(validator_description); 524``` 525 526 It is also possible to create a subclass of `CLI::Validator`, in which case it can also set a custom description function, and operation function. 527 528##### Querying Validators 529 530Once loaded into an Option, a pointer to a named Validator can be retrieved via 531 532```cpp 533opt->get_validator(name); 534``` 535 536This will retrieve a Validator with the given name or throw a `CLI::OptionNotFound` error. If no name is given or name is empty the first unnamed Validator will be returned or the first Validator if there is only one. 537 538or 539 540```cpp 541opt->get_validator(index); 542``` 543 544Which will return a validator in the index it is applied which isn't necessarily the order in which was defined. The pointer can be `nullptr` if an invalid index is given. 545Validators have a few functions to query the current values: 546 547* `get_description()`: Will return a description string 548* `get_name()`: Will return the Validator name 549* `get_active()`: Will return the current active state, true if the Validator is active. 550* `get_application_index()`: Will return the current application index. 551* `get_modifying()`: Will return true if the Validator is allowed to modify the input, this can be controlled via the `non_modifying()` method, though it is recommended to let `check` and `transform` option methods manipulate it if needed. 552 553#### Getting results 554 555In most cases, the fastest and easiest way is to return the results through a callback or variable specified in one of the `add_*` functions. But there are situations where this is not possible or desired. For these cases the results may be obtained through one of the following functions. Please note that these functions will do any type conversions and processing during the call so should not used in performance critical code: 556 557* `->results()`: Retrieves a vector of strings with all the results in the order they were given. 558* `->results(variable_to_bind_to)`: Gets the results according to the MultiOptionPolicy and converts them just like the `add_option_function` with a variable. 559* `Value=opt->as<type>()`: Returns the result or default value directly as the specified type if possible, can be vector to return all results, and a non-vector to get the result according to the MultiOptionPolicy in place. 560 561### Subcommands 562 563Subcommands are supported, and can be nested infinitely. To add a subcommand, call the `add_subcommand` method with a name and an optional description. This gives a pointer to an `App` that behaves just like the main app, and can take options or further subcommands. Add `->ignore_case()` to a subcommand to allow any variation of caps to also be accepted. `->ignore_underscore()` is similar, but for underscores. Children inherit the current setting from the parent. You cannot add multiple matching subcommand names at the same level (including `ignore_case` and `ignore_underscore`). 564 565If you want to require that at least one subcommand is given, use `.require_subcommand()` on the parent app. You can optionally give an exact number of subcommands to require, as well. If you give two arguments, that sets the min and max number allowed. 5660 for the max number allowed will allow an unlimited number of subcommands. As a handy shortcut, a single negative value N will set "up to N" values. Limiting the maximum number allows you to keep arguments that match a previous 567subcommand name from matching. 568 569If an `App` (main or subcommand) has been parsed on the command line, `->parsed` will be true (or convert directly to bool). 570All `App`s have a `get_subcommands()` method, which returns a list of pointers to the subcommands passed on the command line. A `got_subcommand(App_or_name)` method is also provided that will check to see if an `App` pointer or a string name was collected on the command line. 571 572For many cases, however, using an app's callback capabilities may be easier. Every app has a set of callbacks that can be executed at various stages of parsing; a `C++` lambda function (with capture to get parsed values) can be used as input to the callback definition function. If you throw `CLI::Success` or `CLI::RuntimeError(return_value)`, you can 573even exit the program through the callback. 574 575Multiple subcommands are allowed, to allow [`Click`][click] like series of commands (order is preserved). The same subcommand can be triggered multiple times but all positional arguments will take precedence over the second and future calls of the subcommand. `->count()` on the subcommand will return the number of times the subcommand was called. The subcommand callback will only be triggered once unless the `.immediate_callback()` flag is set or the callback is specified through the `parse_complete_callback()` function. The `final_callback()` is triggered only once. In which case the callback executes on completion of the subcommand arguments but after the arguments for that subcommand have been parsed, and can be triggered multiple times. 576 577Subcommands may also have an empty name either by calling `add_subcommand` with an empty string for the name or with no arguments. 578Nameless subcommands function a similarly to groups in the main `App`. See [Option groups](#option-groups) to see how this might work. If an option is not defined in the main App, all nameless subcommands are checked as well. This allows for the options to be defined in a composable group. The `add_subcommand` function has an overload for adding a `shared_ptr<App>` so the subcommand(s) could be defined in different components and merged into a main `App`, or possibly multiple `Apps`. Multiple nameless subcommands are allowed. Callbacks for nameless subcommands are only triggered if any options from the subcommand were parsed. Subcommand names given through the `add_subcommand` method have the same restrictions as option names. 579 580#### Subcommand options 581 582There are several options that are supported on the main app and subcommands and option_groups. These are: 583 584* `.ignore_case()`: Ignore the case of this subcommand. Inherited by added subcommands, so is usually used on the main `App`. 585* `.ignore_underscore()`: Ignore any underscores in the subcommand name. Inherited by added subcommands, so is usually used on the main `App`. 586* `.allow_windows_style_options()`: Allow command line options to be parsed in the form of `/s /long /file:file_name.ext` This option does not change how options are specified in the `add_option` calls or the ability to process options in the form of `-s --long --file=file_name.ext`. 587* `.fallthrough()`: Allow extra unmatched options and positionals to "fall through" and be matched on a parent option. Subcommands always are allowed to "fall through" as in they will first attempt to match on the current subcommand and if they fail will progressively check parents for matching subcommands. 588* `.configurable()`: Allow the subcommand to be triggered from a configuration file. By default subcommand options in a configuration file do not trigger a subcommand but will just update default values. 589* `.disable()`: Specify that the subcommand is disabled, if given with a bool value it will enable or disable the subcommand or option group. 590* `.disabled_by_default()`: Specify that at the start of parsing the subcommand/option_group should be disabled. This is useful for allowing some Subcommands to trigger others. 591* `.enabled_by_default()`: Specify that at the start of each parse the subcommand/option_group should be enabled. This is useful for allowing some Subcommands to disable others. 592* `.silent()`: Specify that the subcommand is silent meaning that if used it won't show up in the subcommand list. This allows the use of subcommands as modifiers 593* `.validate_positionals()`: Specify that positionals should pass validation before matching. Validation is specified through `transform`, `check`, and `each` for an option. If an argument fails validation it is not an error and matching proceeds to the next available positional or extra arguments. 594* `.excludes(option_or_subcommand)`: If given an option pointer or pointer to another subcommand, these subcommands cannot be given together. In the case of options, if the option is passed the subcommand cannot be used and will generate an error. 595* `.needs(option_or_subcommand)`: If given an option pointer or pointer to another subcommand, the subcommands will require the given option to have been given before this subcommand is validated which occurs prior to execution of any callback or after parsing is completed. 596* `.require_option()`: Require 1 or more options or option groups be used. 597* `.require_option(N)`: Require `N` options or option groups, if `N>0`, or up to `N` if `N<0`. `N=0` resets to the default to 0 or more. 598* `.require_option(min, max)`: Explicitly set min and max allowed options or option groups. Setting `max` to 0 implies unlimited options. 599* `.require_subcommand()`: Require 1 or more subcommands. 600* `.require_subcommand(N)`: Require `N` subcommands if `N>0`, or up to `N` if `N<0`. `N=0` resets to the default to 0 or more. 601* `.require_subcommand(min, max)`: Explicitly set min and max allowed subcommands. Setting `max` to 0 is unlimited. 602* `.add_subcommand(name="", description="")`: Add a subcommand, returns a pointer to the internally stored subcommand. 603* `.add_subcommand(shared_ptr<App>)`: Add a subcommand by shared_ptr, returns a pointer to the internally stored subcommand. 604* `.remove_subcommand(App)`: Remove a subcommand from the app or subcommand. 605* `.got_subcommand(App_or_name)`: Check to see if a subcommand was received on the command line. 606* `.get_subcommands(filter)`: The list of subcommands that match a particular filter function. 607* `.add_option_group(name="", description="")`: Add an [option group](#option-groups) to an App, an option group is specialized subcommand intended for containing groups of options or other groups for controlling how options interact. 608* `.get_parent()`: Get the parent App or `nullptr` if called on main App. 609* `.get_option(name)`: Get an option pointer by option name will throw if the specified option is not available, nameless subcommands are also searched 610* `.get_option_no_throw(name)`: Get an option pointer by option name. This function will return a `nullptr` instead of throwing if the option is not available. 611* `.get_options(filter)`: Get the list of all defined option pointers (useful for processing the app for custom output formats). 612* `.parse_order()`: Get the list of option pointers in the order they were parsed (including duplicates). 613* `.formatter(fmt)`: Set a formatter, with signature `std::string(const App*, std::string, AppFormatMode)`. See Formatting for more details. 614* `.description(str)`: Set/change the description. 615* `.get_description()`: Access the description. 616* `.alias(str)`: set an alias for the subcommand, this allows subcommands to be called by more than one name. 617* `.parsed()`: True if this subcommand was given on the command line. 618* `.count()`: Returns the number of times the subcommand was called. 619* `.count(option_name)`: Returns the number of times a particular option was called. 620* `.count_all()`: Returns the total number of arguments a particular subcommand processed, on the main App it returns the total number of processed commands. 621* `.name(name)`: Add or change the name. 622* `.callback(void() function)`: Set the callback for an app. Either sets the `pre_parse_callback` or the `final_callback` depending on the value of `immediate_callback`. See [Subcommand callbacks](#callbacks) for some additional details. 623* `.parse_complete_callback(void() function)`: Set the callback that runs at the completion of parsing. For subcommands this is executed at the completion of the single subcommand and can be executed multiple times. See [Subcommand callbacks](#callbacks) for some additional details. 624* `.final_callback(void() function)`: Set the callback that runs at the end of all processing. This is the last thing that is executed before returning. See [Subcommand callbacks](#callbacks) for some additional details. 625* `.immediate_callback()`: Specifies whether the callback for a subcommand should be run as a `parse_complete_callback`(true) or `final_callback`(false). When used on the main app it will execute the main app callback prior to the callbacks for a subcommand if they do not also have the `immediate_callback` flag set. It is preferable to use the `parse_complete_callback` or `final_callback` directly instead of the `callback` and `immediate_callback` if one wishes to control the ordering and timing of callback. Though `immediate_callback` can be used to swap them if that is needed. 626* `.pre_parse_callback(void(std::size_t) function)`: Set a callback that executes after the first argument of an application is processed. See [Subcommand callbacks](#callbacks) for some additional details. 627* `.allow_extras()`: Do not throw an error if extra arguments are left over. 628* `.positionals_at_end()`: Specify that positional arguments occur as the last arguments and throw an error if an unexpected positional is encountered. 629* `.prefix_command()`: Like `allow_extras`, but stop immediately on the first unrecognized item. It is ideal for allowing your app or subcommand to be a "prefix" to calling another app. 630* `.footer(message)`: Set text to appear at the bottom of the help string. 631* `.footer(std::string())`: Set a callback to generate a string that will appear at the end of the help string. 632* `.set_help_flag(name, message)`: Set the help flag name and message, returns a pointer to the created option. 633* `.set_version_flag(name, versionString or callback, help_message)`: Set the version flag name and version string or callback and optional help message, returns a pointer to the created option. 634* `.set_help_all_flag(name, message)`: Set the help all flag name and message, returns a pointer to the created option. Expands subcommands. 635* `.failure_message(func)`: Set the failure message function. Two provided: `CLI::FailureMessage::help` and `CLI::FailureMessage::simple` (the default). 636* `.group(name)`: Set a group name, defaults to `"Subcommands"`. Setting `""` will be hide the subcommand. 637* `[option_name]`: retrieve a const pointer to an option given by `option_name` for Example `app["--flag1"]` will get a pointer to the option for the "--flag1" value, `app["--flag1"]->as<bool>()` will get the results of the command line for a flag. The operation will throw an exception if the option name is not valid. 638 639> Note: if you have a fixed number of required positional options, that will match before subcommand names. `{}` is an empty filter function, and any positional argument will match before repeated subcommand names. 640 641#### Callbacks 642 643A subcommand has three optional callbacks that are executed at different stages of processing. The `preparse_callback` is executed once after the first argument of a subcommand or application is processed and gives an argument for the number of remaining arguments to process. For the main app the first argument is considered the program name, for subcommands the first argument is the subcommand name. For Option groups and nameless subcommands the first argument is after the first argument or subcommand is processed from that group. 644The second callback is executed after parsing. This is known as the `parse_complete_callback`. For subcommands this is executed immediately after parsing and can be executed multiple times if a subcommand is called multiple times. On the main app this callback is executed after all the `parse_complete_callback`s for the subcommands are executed but prior to any `final_callback` calls in the subcommand or option groups. If the main app or subcommand has a config file, no data from the config file will be reflected in `parse_complete_callback` on named subcommands. For `option_group`s the `parse_complete_callback` is executed prior to the `parse_complete_callback` on the main app but after the `config_file` is loaded (if specified). The `final_callback` is executed after all processing is complete. After the `parse_complete_callback` is executed on the main app, the used subcommand `final_callback` are executed followed by the "final callback" for option groups. The last thing to execute is the `final_callback` for the `main_app`. 645For example say an application was set up like 646 647```cpp 648app.parse_complete_callback(ac1); 649app.final_callback(ac2); 650auto sub1=app.add_subcommand("sub1")->parse_complete_callback(c1)->preparse_callback(pc1); 651auto sub2=app.add_subcommand("sub2")->final_callback(c2)->preparse_callback(pc2); 652app.preparse_callback( pa); 653 654... A bunch of other options 655``` 656 657Then the command line is given as 658 659```bash 660program --opt1 opt1_val sub1 --sub1opt --sub1optb val sub2 --sub2opt sub1 --sub1opt2 sub2 --sub2opt2 val 661``` 662 663* `pa` will be called prior to parsing any values with an argument of 13. 664* `pc1` will be called immediately after processing the `sub1` command with a value of 10. 665* `c1` will be called when the `sub2` command is encountered. 666* `pc2` will be called with value of 6 after the `sub2` command is encountered. 667* `c1` will be called again after the second `sub2` command is encountered. 668* `ac1` will be called after processing of all arguments 669* `c2` will be called once after processing all arguments. 670* `ac2` will be called last after completing all lower level callbacks have been executed. 671 672A subcommand is considered terminated when one of the following conditions are met. 673 6741. There are no more arguments to process 6752. Another subcommand is encountered that would not fit in an optional slot of the subcommand 6763. The `positional_mark` (`--`) is encountered and there are no available positional slots in the subcommand. 6774. The `subcommand_terminator` mark (`++`) is encountered 678 679Prior to executed a `parse_complete_callback` all contained options are processed before the callback is triggered. If a subcommand with a `parse_complete_callback` is called again, then the contained options are reset, and can be triggered again. 680 681#### Option groups 682 683The subcommand method 684 685```cpp 686.add_option_group(name,description) 687``` 688 689Will create an option group, and return a pointer to it. The argument for `description` is optional and can be omitted. An option group allows creation of a collection of options, similar to the groups function on options, but with additional controls and requirements. They allow specific sets of options to be composed and controlled as a collective. For an example see [range example](https://github.com/CLIUtils/CLI11/blob/main/examples/ranges.cpp). Option groups are a specialization of an App so all [functions](#subcommand-options) that work with an App or subcommand also work on option groups. Options can be created as part of an option group using the add functions just like a subcommand, or previously created options can be added through. The name given in an option group must not contain newlines or null characters.�� 690 691```cpp 692ogroup->add_option(option_pointer); 693ogroup->add_options(option_pointer); 694ogroup->add_options(option1,option2,option3,...); 695``` 696 697The option pointers used in this function must be options defined in the parent application of the option group otherwise an error will be generated. Subcommands can also be added via 698 699```cpp 700ogroup->add_subcommand(subcom_pointer); 701``` 702 703This results in the subcommand being moved from its parent into the option group. 704 705Options in an option group are searched for a command line match after any options in the main app, so any positionals in the main app would be matched first. So care must be taken to make sure of the order when using positional arguments and option groups. 706Option groups work well with `excludes` and `require_options` methods, as an application will treat an option group as a single option for the purpose of counting and requirements, and an option group will be considered used if any of the options or subcommands contained in it are used. Option groups allow specifying requirements such as requiring 1 of 3 options in one group and 1 of 3 options in a different group. Option groups can contain other groups as well. Disabling an option group will turn off all options within the group. 707 708The `CLI::TriggerOn` and `CLI::TriggerOff` methods are helper functions to allow the use of options/subcommands from one group to trigger another group on or off. 709 710```cpp 711CLI::TriggerOn(group1_pointer, triggered_group); 712CLI::TriggerOff(group2_pointer, disabled_group); 713``` 714 715These functions make use of `preparse_callback`, `enabled_by_default()` and `disabled_by_default`. The triggered group may be a vector of group pointers. These methods should only be used once per group and will override any previous use of the underlying functions. More complex arrangements can be accomplished using similar methodology with a custom `preparse_callback` function that does more. 716 717Additional helper functions `deprecate_option` and `retire_option` are available to deprecate or retire options 718 719```cpp 720CLI::deprecate_option(option *, replacement_name=""); 721CLI::deprecate_option(App,option_name,replacement_name=""); 722``` 723 724will specify that the option is deprecated which will display a message in the help and a warning on first usage. Deprecated options function normally but will add a message in the help and display a warning on first use. 725 726```cpp 727CLI::retire_option(App,option *); 728CLI::retire_option(App,option_name); 729``` 730 731will create an option that does nothing by default and will display a warning on first usage that the option is retired and has no effect. If the option exists it is replaces with a dummy option that takes the same arguments. 732 733If an empty string is passed the option group name the entire group will be hidden in the help results. For example. 734 735```cpp 736auto hidden_group=app.add_option_group(""); 737``` 738 739will create a group such that no options in that group are displayed in the help string. 740 741### Configuration file 742 743```cpp 744app.set_config(option_name="", 745 default_file_name="", 746 help_string="Read an ini file", 747 required=false) 748``` 749 750If this is called with no arguments, it will remove the configuration file option (like `set_help_flag`). Setting a configuration option is special. If it is present, it will be read along with the normal command line arguments. The file will be read if it exists, and does not throw an error unless `required` is `true`. Configuration files are in [TOML][] format by default, though the default reader can also accept files in INI format as well. It should be noted that CLI11 does not contain a full TOML parser but can read strings from most TOML file and run them through the CLI11 parser. Other formats can be added by an adept user, some variations are available through customization points in the default formatter. An example of a TOML file: 751 752```toml 753# Comments are supported, using a # 754# The default section is [default], case insensitive 755 756value = 1 757str = "A string" 758vector = [1,2,3] 759str_vector = ["one","two","and three"] 760 761# Sections map to subcommands 762[subcommand] 763in_subcommand = Wow 764sub.subcommand = true 765``` 766 767or equivalently in INI format 768 769```ini 770; Comments are supported, using a ; 771; The default section is [default], case insensitive 772 773value = 1 774str = "A string" 775vector = 1 2 3 776str_vector = "one" "two" "and three" 777 778; Sections map to subcommands 779[subcommand] 780in_subcommand = Wow 781sub.subcommand = true 782``` 783 784Spaces 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`, `enable`; or `false`, `off`, `0`, `no`, `disable` (case insensitive). Sections (and `.` separated names) are treated as subcommands (note: this does not necessarily mean that subcommand was passed, it just sets the "defaults"). You cannot set positional-only arguments. Subcommands can be triggered from configuration files if the `configurable` flag was set on the subcommand. Then the use of `[subcommand]` notation will trigger a subcommand and cause it to act as if it were on the command line. 785 786To print a configuration file from the passed 787arguments, use `.config_to_str(default_also=false, write_description=false)`, where `default_also` will also show any defaulted arguments, and `write_description` will include the app and option descriptions. See [Config files](https://cliutils.github.io/CLI11/book/chapters/config.html) for some additional details and customization points. 788 789If it is desired that multiple configuration be allowed. Use 790 791```cpp 792app.set_config("--config")->expected(1, X); 793``` 794 795Where X is some positive number and will allow up to `X` configuration files to be specified by separate `--config` arguments. Value strings with quote characters in it will be printed with a single quote. All other arguments will use double quote. Empty strings will use a double quoted argument. Numerical or boolean values are not quoted. 796 797### Inheriting defaults 798 799Many of the defaults for subcommands and even options are inherited from their creators. The inherited default values for subcommands are `allow_extras`, `prefix_command`, `ignore_case`, `ignore_underscore`, `fallthrough`, `group`, `footer`,`immediate_callback` and maximum number of required subcommands. The help flag existence, name, and description are inherited, as well. 800 801Options have defaults for `group`, `required`, `multi_option_policy`, `ignore_case`, `ignore_underscore`, `delimiter`, and `disable_flag_override`. To set these defaults, you should set the `option_defaults()` object, for example: 802 803```cpp 804app.option_defaults()->required(); 805// All future options will be required 806``` 807 808The default settings for options are inherited to subcommands, as well. 809 810### Formatting 811 812The job of formatting help printouts is delegated to a formatter callable object on Apps and Options. You are free to replace either formatter by calling `formatter(fmt)` on an `App`, where fmt is any copyable callable with the correct signature. 813CLI11 comes with a default App formatter functional, `Formatter`. It is customizable; you can set `label(key, value)` to replace the default labels like `REQUIRED`, and `column_width(n)` to set the width of the columns before you add the functional to the app or option. You can also override almost any stage of the formatting process in a subclass of either formatter. If you want to make a new formatter from scratch, you can do 814that too; you just need to implement the correct signature. The first argument is a const pointer to the in question. The formatter will get a `std::string` usage name as the second option, and a `AppFormatMode` mode for the final option. It should return a `std::string`. 815 816The `AppFormatMode` can be `Normal`, `All`, or `Sub`, and it indicates the situation the help was called in. `Sub` is optional, but the default formatter uses it to make sure expanded subcommands are called with 817their own formatter since you can't access anything but the call operator once a formatter has been set. 818 819### Subclassing 820 821The App class was designed allow toolkits to subclass it, to provide preset default options (see above) and setup/teardown code. Subcommands remain an unsubclassed `App`, since those are not expected to need setup and teardown. The default `App` only adds a help flag, `-h,--help`, than can removed/replaced using `.set_help_flag(name, help_string)`. You can also set a help-all flag with `.set_help_all_flag(name, help_string)`; this will expand the subcommands (one level only). You can remove options if you have pointers to them using `.remove_option(opt)`. You can add a `pre_callback` override to customize the after parse 822but before run behavior, while 823still giving the user freedom to `callback` on the main app. 824 825The most important parse function is `parse(std::vector<std::string>)`, which takes a reversed list of arguments (so that `pop_back` processes the args in the correct order). `get_help_ptr` and `get_config_ptr` give you access to the help/config option pointers. The standard `parse` manually sets the name from the first argument, so it should not be in this vector. You can also use `parse(string, bool)` to split up and parse a single string; the optional boolean should be set to true if you are 826including the program name in the string, and false otherwise. The program name can contain spaces if it is an existing file, otherwise can be enclosed in quotes(single quote, double quote or backtick). Embedded quote characters can be escaped with `\`. 827 828Also, in a related note, the `App` you get a pointer to is stored in the parent `App` in a `shared_ptr`s (similar to `Option`s) and are deleted when the main `App` goes out of scope unless the object has another owner. 829 830### How it works 831 832Every `add_` option you have seen so far depends on one method that takes a lambda function. Each of these methods is just making a different lambda function with capture to populate the option. The function has full access to the vector of strings, so it knows how many times an option was passed or how many arguments it received. The lambda returns `true` if it could validate the option strings, and 833`false` if it failed. 834 835Other values can be added as long as they support `operator>>` (and defaults can be printed if they support `operator<<`). To add a new type, for example, provide a custom `operator>>` with an `istream` (inside the CLI namespace is fine if you don't want to interfere with an existing `operator>>`). 836 837If you wanted to extend this to support a completely new type, use a lambda or add a specialization of the `lexical_cast` function template in the namespace of the type you need to convert to. Some examples of some new parsers for `complex<double>` that support all of the features of a standard `add_options` call are in [one of the tests](./tests/NewParseTest.cpp). A simpler example is shown below: 838 839#### Example 840 841```cpp 842app.add_option("--fancy-count", [](std::vector<std::string> val){ 843 std::cout << "This option was given " << val.size() << " times." << std::endl; 844 return true; 845 }); 846``` 847 848### Utilities 849 850There are a few other utilities that are often useful in CLI programming. These are in separate headers, and do not appear in `CLI11.hpp`, but are completely independent and can be used as needed. The `Timer`/`AutoTimer` class allows you to easily time a block of code, with custom print output. 851 852```cpp 853{ 854CLI::AutoTimer timer {"My Long Process", CLI::Timer::Big}; 855some_long_running_process(); 856} 857``` 858 859This will create a timer with a title (default: `Timer`), and will customize the output using the predefined `Big` output (default: `Simple`). Because it is an `AutoTimer`, it will print out the time elapsed when the timer is destroyed at the end of the block. If you use `Timer` instead, you can use `to_string` or `std::cout << timer << std::endl;` to print the time. The print function can be any function that takes two strings, the title and the time, and returns a formatted 860string for printing. 861 862### Other libraries 863 864If you use the excellent [Rang][] library to add color to your terminal in a safe, multi-platform way, you can combine it with CLI11 nicely: 865 866```cpp 867std::atexit([](){std::cout << rang::style::reset;}); 868try { 869 app.parse(argc, argv); 870} catch (const CLI::ParseError &e) { 871 std::cout << (e.get_exit_code()==0 ? rang::fg::blue : rang::fg::red); 872 return app.exit(e); 873} 874``` 875 876This will print help in blue, errors in red, and will reset before returning the terminal to the user. 877 878If you are on a Unix-like system, and you'd like to handle control-c and color, you can add: 879 880```cpp 881 #include <csignal> 882 void signal_handler(int s) { 883 std::cout << std::endl << rang::style::reset << rang::fg::red << rang::fg::bold; 884 std::cout << "Control-C detected, exiting..." << rang::style::reset << std::endl; 885 std::exit(1); // will call the correct exit func, no unwinding of the stack though 886 } 887``` 888 889And, in your main function: 890 891```cpp 892 // Nice Control-C 893 struct sigaction sigIntHandler; 894 sigIntHandler.sa_handler = signal_handler; 895 sigemptyset(&sigIntHandler.sa_mask); 896 sigIntHandler.sa_flags = 0; 897 sigaction(SIGINT, &sigIntHandler, nullptr); 898``` 899 900## API 901 902The API is [documented here][api-docs]. Also see the [CLI11 tutorial GitBook][gitbook]. 903 904## Examples 905 906Several short examples of different features are included in the repository. A brief description of each is included here 907 908* [callback_passthrough](https://github.com/CLIUtils/CLI11/blob/main/examples/callback_passthrough.cpp): Example of directly passing remaining arguments through to a callback function which generates a CLI11 application based on existing arguments. 909* [custom_parse](https://github.com/CLIUtils/CLI11/blob/main/examples/custom_parse.cpp): Based on [Issue #566](https://github.com/CLIUtils/CLI11/issues/566), example of custom parser 910* [digit_args](https://github.com/CLIUtils/CLI11/blob/main/examples/digit_args.cpp): Based on [Issue #123](https://github.com/CLIUtils/CLI11/issues/123), uses digit flags to pass a value 911* [enum](https://github.com/CLIUtils/CLI11/blob/main/examples/enum.cpp): Using enumerations in an option, and the use of [CheckedTransformer](#transforming-validators) 912* [enum_ostream](https://github.com/CLIUtils/CLI11/blob/main/examples/enum_ostream.cpp): In addition to the contents of example enum.cpp, this example shows how a custom ostream operator overrides CLI11's enum streaming. 913* [formatter](https://github.com/CLIUtils/CLI11/blob/main/examples/formatter.cpp): Illustrating usage of a custom formatter 914* [groups](https://github.com/CLIUtils/CLI11/blob/main/examples/groups.cpp): Example using groups of options for help grouping and a the timer helper class 915* [inter_argument_order](https://github.com/CLIUtils/CLI11/blob/main/examples/inter_argument_order.cpp): An app to practice mixing unlimited arguments, but still recover the original order. 916* [json](https://github.com/CLIUtils/CLI11/blob/main/examples/json.cpp): Using JSON as a config file parser 917* [modhelp](https://github.com/CLIUtils/CLI11/blob/main/examples/modhelp.cpp): How to modify the help flag to do something other than default 918* [nested](https://github.com/CLIUtils/CLI11/blob/main/examples/nested.cpp): Nested subcommands 919* [option_groups](https://github.com/CLIUtils/CLI11/blob/main/examples/option_groups.cpp): Illustrating the use of option groups and a required number of options. Based on [Issue #88](https://github.com/CLIUtils/CLI11/issues/88) to set interacting groups of options 920* [positional_arity](https://github.com/CLIUtils/CLI11/blob/main/examples/positional_arity.cpp): Illustrating use of `preparse_callback` to handle situations where the number of arguments can determine which should get parsed, Based on [Issue #166](https://github.com/CLIUtils/CLI11/issues/166) 921* [positional_validation](https://github.com/CLIUtils/CLI11/blob/main/examples/positional_validation.cpp): Example of how positional arguments are validated using the `validate_positional` flag, also based on [Issue #166](https://github.com/CLIUtils/CLI11/issues/166) 922* [prefix_command](https://github.com/CLIUtils/CLI11/blob/main/examples/prefix_command.cpp): Illustrating use of the `prefix_command` flag. 923* [ranges](https://github.com/CLIUtils/CLI11/blob/main/examples/ranges.cpp): App to demonstrate exclusionary option groups based on [Issue #88](https://github.com/CLIUtils/CLI11/issues/88) 924* [shapes](https://github.com/CLIUtils/CLI11/blob/main/examples/shapes.cpp): Illustrating how to set up repeated subcommands Based on [gitter discussion](https://gitter.im/CLI11gitter/Lobby?at=5c7af6b965ffa019ea788cd5) 925* [simple](https://github.com/CLIUtils/CLI11/blob/main/examples/simple.cpp): A simple example of how to set up a CLI11 Application with different flags and options 926* [subcom_help](https://github.com/CLIUtils/CLI11/blob/main/examples/subcom_help.cpp): Configuring help for subcommands 927* [subcom_partitioned](https://github.com/CLIUtils/CLI11/blob/main/examples/subcom_partitioned.cpp): Example with a timer and subcommands generated separately and added to the main app later. 928* [subcommands](https://github.com/CLIUtils/CLI11/blob/main/examples/subcommands.cpp): Short example of subcommands 929* [validators](https://github.com/CLIUtils/CLI11/blob/main/examples/validators.cpp): Example illustrating use of validators 930 931## Contribute 932 933To contribute, open an [issue][github issues] or [pull request][github pull requests] on GitHub, or ask a question on [gitter][]. There is also a short note to contributors [here](./.github/CONTRIBUTING.md). 934This readme roughly follows the [Standard Readme Style][] and includes a mention of almost every feature of the library. More complex features are documented in more detail in the [CLI11 tutorial GitBook][gitbook]. 935 936This project was created by [Henry Schreiner](https://github.com/henryiii) and major features were added by [Philip Top](https://github.com/phlptp). Special thanks to all the contributors ([emoji key](https://allcontributors.org/docs/en/emoji-key)): 937 938<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --> 939<!-- prettier-ignore-start --> 940<!-- markdownlint-disable --> 941<table> 942 <tr> 943 <td align="center"><a href="http://iscinumpy.gitlab.io"><img src="https://avatars1.githubusercontent.com/u/4616906?v=4" width="100px;" alt=""/><br /><sub><b>Henry Schreiner</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Ahenryiii" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=henryiii" title="Documentation">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=henryiii" title="Code">��</a></td> 944 <td align="center"><a href="https://github.com/phlptp"><img src="https://avatars0.githubusercontent.com/u/20667153?v=4" width="100px;" alt=""/><br /><sub><b>Philip Top</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Aphlptp" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=phlptp" title="Documentation">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=phlptp" title="Code">��</a></td> 945 <td align="center"><a href="https://www.linkedin.com/in/cbachhuber/"><img src="https://avatars0.githubusercontent.com/u/27212661?v=4" width="100px;" alt=""/><br /><sub><b>Christoph Bachhuber</b></sub></a><br /><a href="#example-cbachhuber" title="Examples">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=cbachhuber" title="Code">��</a></td> 946 <td align="center"><a href="https://lambdafu.net/"><img src="https://avatars1.githubusercontent.com/u/1138455?v=4" width="100px;" alt=""/><br /><sub><b>Marcus Brinkmann</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Alambdafu" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=lambdafu" title="Code">��</a></td> 947 <td align="center"><a href="https://github.com/SkyToGround"><img src="https://avatars1.githubusercontent.com/u/58835?v=4" width="100px;" alt=""/><br /><sub><b>Jonas Nilsson</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3ASkyToGround" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=SkyToGround" title="Code">��</a></td> 948 <td align="center"><a href="https://github.com/dvj"><img src="https://avatars2.githubusercontent.com/u/77217?v=4" width="100px;" alt=""/><br /><sub><b>Doug Johnston</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Advj" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=dvj" title="Code">��</a></td> 949 <td align="center"><a href="http://lucas-czech.de"><img src="https://avatars0.githubusercontent.com/u/4741887?v=4" width="100px;" alt=""/><br /><sub><b>Lucas Czech</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Alczech" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=lczech" title="Code">��</a></td> 950 </tr> 951 <tr> 952 <td align="center"><a href="https://github.com/rafiw"><img src="https://avatars3.githubusercontent.com/u/3034707?v=4" width="100px;" alt=""/><br /><sub><b>Rafi Wiener</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Arafiw" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=rafiw" title="Code">��</a></td> 953 <td align="center"><a href="https://github.com/mensinda"><img src="https://avatars3.githubusercontent.com/u/3407462?v=4" width="100px;" alt=""/><br /><sub><b>Daniel Mensinger</b></sub></a><br /><a href="#platform-mensinda" title="Packaging/porting to new platform">��</a></td> 954 <td align="center"><a href="https://github.com/jbriales"><img src="https://avatars1.githubusercontent.com/u/6850478?v=4" width="100px;" alt=""/><br /><sub><b>Jesus Briales</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=jbriales" title="Code">��</a> <a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Ajbriales" title="Bug reports">��</a></td> 955 <td align="center"><a href="https://seanfisk.com/"><img src="https://avatars0.githubusercontent.com/u/410322?v=4" width="100px;" alt=""/><br /><sub><b>Sean Fisk</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Aseanfisk" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=seanfisk" title="Code">��</a></td> 956 <td align="center"><a href="https://github.com/fpeng1985"><img src="https://avatars1.githubusercontent.com/u/87981?v=4" width="100px;" alt=""/><br /><sub><b>fpeng1985</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=fpeng1985" title="Code">��</a></td> 957 <td align="center"><a href="https://github.com/almikhayl"><img src="https://avatars2.githubusercontent.com/u/6747040?v=4" width="100px;" alt=""/><br /><sub><b>almikhayl</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=almikhayl" title="Code">��</a> <a href="#platform-almikhayl" title="Packaging/porting to new platform">��</a></td> 958 <td align="center"><a href="https://github.com/andrew-hardin"><img src="https://avatars0.githubusercontent.com/u/16496326?v=4" width="100px;" alt=""/><br /><sub><b>Andrew Hardin</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=andrew-hardin" title="Code">��</a></td> 959 </tr> 960 <tr> 961 <td align="center"><a href="https://github.com/SX91"><img src="https://avatars2.githubusercontent.com/u/754754?v=4" width="100px;" alt=""/><br /><sub><b>Anton</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=SX91" title="Code">��</a></td> 962 <td align="center"><a href="https://github.com/helmesjo"><img src="https://avatars0.githubusercontent.com/u/2501070?v=4" width="100px;" alt=""/><br /><sub><b>Fred Helmesjö</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Ahelmesjo" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=helmesjo" title="Code">��</a></td> 963 <td align="center"><a href="https://github.com/skannan89"><img src="https://avatars0.githubusercontent.com/u/11918764?v=4" width="100px;" alt=""/><br /><sub><b>Kannan</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Askannan89" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=skannan89" title="Code">��</a></td> 964 <td align="center"><a href="http://himvis.com"><img src="https://avatars3.githubusercontent.com/u/465279?v=4" width="100px;" alt=""/><br /><sub><b>Khem Raj</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=kraj" title="Code">��</a></td> 965 <td align="center"><a href="https://www.mogigoma.com/"><img src="https://avatars2.githubusercontent.com/u/130862?v=4" width="100px;" alt=""/><br /><sub><b>Mak Kolybabi</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=mogigoma" title="Documentation">��</a></td> 966 <td align="center"><a href="http://msoeken.github.io"><img src="https://avatars0.githubusercontent.com/u/1998245?v=4" width="100px;" alt=""/><br /><sub><b>Mathias Soeken</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=msoeken" title="Documentation">��</a></td> 967 <td align="center"><a href="https://github.com/nathanhourt"><img src="https://avatars2.githubusercontent.com/u/271977?v=4" width="100px;" alt=""/><br /><sub><b>Nathan Hourt</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Anathanhourt" title="Bug reports">��</a> <a href="https://github.com/CLIUtils/CLI11/commits?author=nathanhourt" title="Code">��</a></td> 968 </tr> 969 <tr> 970 <td align="center"><a href="https://github.com/pleroux0"><img src="https://avatars2.githubusercontent.com/u/39619854?v=4" width="100px;" alt=""/><br /><sub><b>Paul le Roux</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=pleroux0" title="Code">��</a> <a href="#platform-pleroux0" title="Packaging/porting to new platform">��</a></td> 971 <td align="center"><a href="https://github.com/chfast"><img src="https://avatars1.githubusercontent.com/u/573380?v=4" width="100px;" alt=""/><br /><sub><b>Paweł Bylica</b></sub></a><br /><a href="#platform-chfast" title="Packaging/porting to new platform">��</a></td> 972 <td align="center"><a href="https://github.com/peterazmanov"><img src="https://avatars0.githubusercontent.com/u/15322318?v=4" width="100px;" alt=""/><br /><sub><b>Peter Azmanov</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=peterazmanov" title="Code">��</a></td> 973 <td align="center"><a href="https://github.com/delpinux"><img src="https://avatars0.githubusercontent.com/u/35096584?v=4" width="100px;" alt=""/><br /><sub><b>Stéphane Del Pino</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=delpinux" title="Code">��</a></td> 974 <td align="center"><a href="https://github.com/metopa"><img src="https://avatars2.githubusercontent.com/u/3974178?v=4" width="100px;" alt=""/><br /><sub><b>Viacheslav Kroilov</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=metopa" title="Code">��</a></td> 975 <td align="center"><a href="http://cs.odu.edu/~ctsolakis"><img src="https://avatars0.githubusercontent.com/u/6725596?v=4" width="100px;" alt=""/><br /><sub><b>christos</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=ChristosT" title="Code">��</a></td> 976 <td align="center"><a href="https://github.com/deining"><img src="https://avatars3.githubusercontent.com/u/18169566?v=4" width="100px;" alt=""/><br /><sub><b>deining</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=deining" title="Documentation">��</a></td> 977 </tr> 978 <tr> 979 <td align="center"><a href="https://github.com/elszon"><img src="https://avatars0.githubusercontent.com/u/2971495?v=4" width="100px;" alt=""/><br /><sub><b>elszon</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=elszon" title="Code">��</a></td> 980 <td align="center"><a href="https://github.com/ncihnegn"><img src="https://avatars3.githubusercontent.com/u/12021721?v=4" width="100px;" alt=""/><br /><sub><b>ncihnegn</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=ncihnegn" title="Code">��</a></td> 981 <td align="center"><a href="https://github.com/nurelin"><img src="https://avatars3.githubusercontent.com/u/5276274?v=4" width="100px;" alt=""/><br /><sub><b>nurelin</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=nurelin" title="Code">��</a></td> 982 <td align="center"><a href="https://github.com/ryan4729"><img src="https://avatars3.githubusercontent.com/u/40183301?v=4" width="100px;" alt=""/><br /><sub><b>ryan4729</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=ryan4729" title="Tests">⚠️</a></td> 983 <td align="center"><a href="https://izzys.casa"><img src="https://avatars0.githubusercontent.com/u/63051?v=4" width="100px;" alt=""/><br /><sub><b>Isabella Muerte</b></sub></a><br /><a href="#platform-slurps-mad-rips" title="Packaging/porting to new platform">��</a></td> 984 <td align="center"><a href="https://github.com/KOLANICH"><img src="https://avatars1.githubusercontent.com/u/240344?v=4" width="100px;" alt=""/><br /><sub><b>KOLANICH</b></sub></a><br /><a href="#platform-KOLANICH" title="Packaging/porting to new platform">��</a></td> 985 <td align="center"><a href="https://github.com/jgerityneurala"><img src="https://avatars2.githubusercontent.com/u/57360646?v=4" width="100px;" alt=""/><br /><sub><b>James Gerity</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=jgerityneurala" title="Documentation">��</a></td> 986 </tr> 987 <tr> 988 <td align="center"><a href="https://github.com/jsoref"><img src="https://avatars0.githubusercontent.com/u/2119212?v=4" width="100px;" alt=""/><br /><sub><b>Josh Soref</b></sub></a><br /><a href="#tool-jsoref" title="Tools">��</a></td> 989 <td align="center"><a href="https://github.com/geir-t"><img src="https://avatars3.githubusercontent.com/u/35292136?v=4" width="100px;" alt=""/><br /><sub><b>geir-t</b></sub></a><br /><a href="#platform-geir-t" title="Packaging/porting to new platform">��</a></td> 990 <td align="center"><a href="https://ondrejcertik.com/"><img src="https://avatars3.githubusercontent.com/u/20568?v=4" width="100px;" alt=""/><br /><sub><b>Ondřej Čertík</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/issues?q=author%3Acertik" title="Bug reports">��</a></td> 991 <td align="center"><a href="http://sam.hocevar.net/"><img src="https://avatars2.githubusercontent.com/u/245089?v=4" width="100px;" alt=""/><br /><sub><b>Sam Hocevar</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=samhocevar" title="Code">��</a></td> 992 <td align="center"><a href="http://www.ratml.org/"><img src="https://avatars0.githubusercontent.com/u/1845039?v=4" width="100px;" alt=""/><br /><sub><b>Ryan Curtin</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=rcurtin" title="Documentation">��</a></td> 993 <td align="center"><a href="https://mbh.sh"><img src="https://avatars3.githubusercontent.com/u/20403931?v=4" width="100px;" alt=""/><br /><sub><b>Michael Hall</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=mbhall88" title="Documentation">��</a></td> 994 <td align="center"><a href="https://github.com/ferdymercury"><img src="https://avatars3.githubusercontent.com/u/10653970?v=4" width="100px;" alt=""/><br /><sub><b>ferdymercury</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=ferdymercury" title="Documentation">��</a></td> 995 </tr> 996 <tr> 997 <td align="center"><a href="https://github.com/jakoblover"><img src="https://avatars0.githubusercontent.com/u/14160441?v=4" width="100px;" alt=""/><br /><sub><b>Jakob Lover</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=jakoblover" title="Code">��</a></td> 998 <td align="center"><a href="https://github.com/ZeeD26"><img src="https://avatars2.githubusercontent.com/u/2487468?v=4" width="100px;" alt=""/><br /><sub><b>Dominik Steinberger</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=ZeeD26" title="Code">��</a></td> 999 <td align="center"><a href="https://github.com/dfleury2"><img src="https://avatars1.githubusercontent.com/u/4805384?v=4" width="100px;" alt=""/><br /><sub><b>D. Fleury</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=dfleury2" title="Code">��</a></td> 1000 <td align="center"><a href="https://github.com/dbarowy"><img src="https://avatars3.githubusercontent.com/u/573142?v=4" width="100px;" alt=""/><br /><sub><b>Dan Barowy</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=dbarowy" title="Documentation">��</a></td> 1001 <td align="center"><a href="https://github.com/paddy-hack"><img src="https://avatars.githubusercontent.com/u/6804372?v=4" width="100px;" alt=""/><br /><sub><b>Olaf Meeuwissen</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=paddy-hack" title="Code">��</a></td> 1002 <td align="center"><a href="https://github.com/dryleev"><img src="https://avatars.githubusercontent.com/u/83670813?v=4" width="100px;" alt=""/><br /><sub><b>dryleev</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=dryleev" title="Code">��</a></td> 1003 <td align="center"><a href="https://github.com/AnticliMaxtic"><img src="https://avatars.githubusercontent.com/u/43995389?v=4" width="100px;" alt=""/><br /><sub><b>Max</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=AnticliMaxtic" title="Code">��</a></td> 1004 </tr> 1005 <tr> 1006 <td align="center"><a href="https://profiles.sussex.ac.uk/p281168-alex-dewar/publications"><img src="https://avatars.githubusercontent.com/u/23149834?v=4" width="100px;" alt=""/><br /><sub><b>Alex Dewar</b></sub></a><br /><a href="https://github.com/CLIUtils/CLI11/commits?author=alexdewar" title="Code">��</a></td> 1007 </tr> 1008</table> 1009 1010<!-- markdownlint-enable --> 1011<!-- prettier-ignore-end --> 1012<!-- ALL-CONTRIBUTORS-LIST:END --> 1013 1014This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome! 1015 1016## License 1017 1018As of version 1.0, this library is available under a 3-Clause BSD license. See the [LICENSE](./LICENSE) file for details. 1019 1020CLI11 was developed at the [University of Cincinnati][] to support of the [GooFit][] library under [NSF Award 1414736][]. Version 0.9 was featured in a [DIANA/HEP][] meeting at CERN ([see the slides][diana slides]). Please give it a try! Feedback is always welcome. 1021 1022[doi-badge]: https://zenodo.org/badge/80064252.svg 1023[doi-link]: https://zenodo.org/badge/latestdoi/80064252 1024[azure-badge]: https://dev.azure.com/CLIUtils/CLI11/_apis/build/status/CLIUtils.CLI11?branchName=main 1025[azure]: https://dev.azure.com/CLIUtils/CLI11 1026[actions-link]: https://github.com/CLIUtils/CLI11/actions 1027[actions-badge]: https://github.com/CLIUtils/CLI11/actions/workflows/tests.yml/badge.svg 1028[appveyor-badge]: https://ci.appveyor.com/api/projects/status/82niaxpaa28dwbms/branch/main?svg=true 1029[appveyor]: https://ci.appveyor.com/project/HenrySchreiner/cli11 1030[repology-badge]: https://repology.org/badge/latest-versions/cli11.svg 1031[repology]: https://repology.org/project/cli11/versions 1032[codecov-badge]: https://codecov.io/gh/CLIUtils/CLI11/branch/main/graph/badge.svg?token=2O4wfs8NJO 1033[codecov]: https://codecov.io/gh/CLIUtils/CLI11 1034[gitter-badge]: https://badges.gitter.im/CLI11gitter/Lobby.svg 1035[gitter]: https://gitter.im/CLI11gitter/Lobby 1036[license-badge]: https://img.shields.io/badge/License-BSD-blue.svg 1037[conan-badge]: https://img.shields.io/badge/conan-io-blue 1038[conan-link]: https://conan.io/center/cli11 1039[conda-badge]: https://img.shields.io/conda/vn/conda-forge/cli11.svg 1040[conda-link]: https://github.com/conda-forge/cli11-feedstock 1041[github releases]: https://github.com/CLIUtils/CLI11/releases 1042[github issues]: https://github.com/CLIUtils/CLI11/issues 1043[github pull requests]: https://github.com/CLIUtils/CLI11/pulls 1044[goofit]: https://GooFit.github.io 1045[plumbum]: https://plumbum.readthedocs.io/en/latest/ 1046[click]: http://click.pocoo.org 1047[api-docs]: https://CLIUtils.github.io/CLI11/index.html 1048[rang]: https://github.com/agauniyal/rang 1049[boost program options]: http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html 1050[the lean mean c++ option parser]: http://optionparser.sourceforge.net 1051[tclap]: http://tclap.sourceforge.net 1052[cxxopts]: https://github.com/jarro2783/cxxopts 1053[docopt]: https://github.com/docopt/docopt.cpp 1054[gflags]: https://gflags.github.io/gflags 1055[getopt]: https://www.gnu.org/software/libc/manual/html_node/Getopt.html 1056[diana/hep]: http://diana-hep.org 1057[nsf award 1414736]: https://nsf.gov/awardsearch/showAward?AWD_ID=1414736 1058[university of cincinnati]: http://www.uc.edu 1059[gitbook]: https://cliutils.github.io/CLI11/book/ 1060[cli11 advanced topics/custom converters]: https://cliutils.gitlab.io/CLI11Tutorial/chapters/advanced-topics.html#custom-converters 1061[programoptions.hxx]: https://github.com/Fytch/ProgramOptions.hxx 1062[argument aggregator]: https://github.com/vietjtnguyen/argagg 1063[args]: https://github.com/Taywee/args 1064[argh!]: https://github.com/adishavit/argh 1065[fmt]: https://github.com/fmtlib/fmt 1066[catch]: https://github.com/philsquared/Catch 1067[clara]: https://github.com/philsquared/Clara 1068[version 1.0 post]: https://iscinumpy.gitlab.io/post/announcing-cli11-10/ 1069[version 1.3 post]: https://iscinumpy.gitlab.io/post/announcing-cli11-13/ 1070[version 1.6 post]: https://iscinumpy.gitlab.io/post/announcing-cli11-16/ 1071[version 2.0 post]: https://iscinumpy.gitlab.io/post/announcing-cli11-20/ 1072[wandbox-badge]: https://img.shields.io/badge/try_2.1-online-blue.svg 1073[wandbox-link]: https://wandbox.org/permlink/CA5bymNHh0AczdeN 1074[releases-badge]: https://img.shields.io/github/release/CLIUtils/CLI11.svg 1075[cli11-po-compare]: https://iscinumpy.gitlab.io/post/comparing-cli11-and-boostpo/ 1076[diana slides]: https://indico.cern.ch/event/619465/contributions/2507949/attachments/1448567/2232649/20170424-diana-2.pdf 1077[awesome c++]: https://github.com/fffaraz/awesome-cpp/blob/master/README.md#cli 1078[cli]: https://codesynthesis.com/projects/cli/ 1079[single file libs]: https://github.com/nothings/single_file_libs/blob/master/README.md 1080[codacy-badge]: https://app.codacy.com/project/badge/Grade/2796b969c1b54321a02ad08affec0800 1081[codacy-link]: https://www.codacy.com/gh/CLIUtils/CLI11/dashboard?utm_source=github.com&utm_medium=referral&utm_content=CLIUtils/CLI11&utm_campaign=Badge_Grade 1082[hunter]: https://docs.hunter.sh/en/latest/packages/pkg/CLI11.html 1083[standard readme style]: https://github.com/RichardLitt/standard-readme 1084[argparse]: https://github.com/p-ranav/argparse 1085[toml]: https://toml.io 1086
