first

2026-09-13 13:30:21 +08:00
commit a6bbd520cf
2744 changed files with 1598795 additions and 0 deletions
@@ -0,0 +1,123 @@
+# Introduction {#mainpage}
+
+CLI11 lets you write your own command line programs in C++. The library is
+designed to be clean, intuitive, but powerful. There are no requirements beyond
+C++11 support (and even `<regex>` support not required). It works on Mac, Linux,
+and Windows, and has 100% test coverage on all three systems. You can simply
+drop in a single header file (`CLI11.hpp` available in [releases][]) to use
+CLI11 in your own application. Other ways to integrate it into a build system
+are listed in the [README][].
+
+The library was inspired by the Python libraries [Plumbum][] and [Click][], and
+incorporates many of their user friendly features.
+
+The syntax is simple and scales from a basic application to a massive physics
+analysis with multiple models and many parameters and switches. For example,
+this is a simple program that has an optional parameter that defaults to 0:
+
+```text
+$ ./a.out
+Parameter value: 0
+
+$ ./a.out -p 4
+Parameter value: 4
+
+$ ./a.out --help
+App description
+Usage: ./a.out [OPTIONS]
+
+Options:
+  -h,--help                   Print this help message and exit
+  -p INT                      Parameter
+```
+
+Like any good command line application, help is provided. This program can be
+implemented in only a few lines:
+
+\include intro.cpp
+
+[Source code](https://github.com/CLIUtils/CLI11/blob/main/book/code/intro.cpp)
+
+Unlike some other libraries, this is enough to exit correctly and cleanly if
+help is requested or if incorrect arguments are passed. You can try this example
+out for yourself. To compile with GCC:
+
+```text
+c++ -std=c++11 intro.cpp
+```
+
+Much more complicated options are handled elegantly:
+
+```cpp
+std::string file;
+app.add_option("-f,--file", file, "Require an existing file")
+  ->required()
+  ->check(CLI::ExistingFile);
+```
+
+You can use any valid type; the above example could have used a
+`boost::file_system` file instead of a `std::string`. The value is a real value
+and does not require any special lookups to access. You do not have to risk
+typos by repeating the values after parsing like some libraries require. The
+library also handles positional arguments, flags, fixed or unlimited repeating
+options, interdependent options, flags, custom validators, help groups, and
+more.
+
+You can use subcommands, as well. Subcommands support callback lambda functions
+when parsed, or they can be checked later. You can infinitely nest subcommands,
+and each is a full `App` instance, supporting everything listed above.
+
+Reading/producing `.ini` files for configuration is also supported, as is using
+environment variables as input. The base `App` can be subclassed and customized
+for use in a toolkit (like [GooFit][]). All the standard shell idioms, like
+`--`, work as well.
+
+The guide chapters in the sidebar walk through the library step by step,
+starting with [installation](@ref book-installation) and a first program. The
+examples section shows complete programs: the @ref book-an-advanced-example
+walkthrough, and @ref example-programs, an index of the programs that ship with
+CLI11. Feel free to contribute to [the guide here][cli11guide] if something can
+be improved!
+
+## API reference
+
+The main classes are:
+
+| Name           | Where used                                                |
+| -------------- | --------------------------------------------------------- |
+| CLI::Option    | Options, stored in the app                                |
+| CLI::App       | The main application or subcommands                       |
+| CLI::Validator | A check that can affect the type name                     |
+| CLI::Formatter | A subclassable formatter for help printing                |
+| CLI::ExitCode  | A scoped enum with exit codes                             |
+| CLI::Timer     | A timer class, only in CLI/Timer.hpp (not in `CLI11.hpp`) |
+| CLI::AutoTimer | A timer that prints on deletion                           |
+
+Groups of related topics:
+
+| Name                 | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| @ref error_group     | Errors that can be thrown                      |
+| @ref validator_group | Common validators used in CLI::Option::check() |
+
+Full indexes:
+
+- [Errors & Validators](topics.html)
+- [Namespace List](namespaces.html)
+- [Class List](annotated.html)
+
+## About
+
+CLI11 was developed at the [University of Cincinnati][] in support of the
+[GooFit][] library under [NSF Award 1414736][nsf 1414736]. It was featured in a
+[DIANA/HEP][] meeting at CERN. Please give it a try! Feedback is always welcome.
+
+[goofit]: https://github.com/GooFit/GooFit
+[diana/hep]: https://diana-hep.org
+[releases]: https://github.com/CLIUtils/CLI11/releases
+[readme]: https://github.com/CLIUtils/CLI11/blob/main/README.md
+[nsf 1414736]: https://nsf.gov/awardsearch/showAward?AWD_ID=1414736
+[university of cincinnati]: https://www.uc.edu
+[cli11guide]: https://github.com/CLIUtils/CLI11/tree/main/book
+[plumbum]: https://plumbum.readthedocs.io/en/latest/
+[click]: https://click.palletsprojects.com