mirrors/CLI11
1
0
Fork 0
mirror of https://github.com/CLIUtils/CLI11.git synced 2025-04-30 20:53:52 +00:00
Code Issues Releases Wiki Activity

Minor updates to readme

Browse Source
This commit is contained in:
Henry Fredrick Schreiner 2017-03-03 22:04:32 -05:00
parent 0a6863d528
commit bd48b99cee
1 changed files with 6 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
README.md
View File

@ -6,7 +6,7 @@
# CLI11: Command line parser for C++11 # CLI11: Command line parser for C++11
CLI11 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. CLI11 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.
It is tested on [Travis](https://travis-ci.org/henryiii/CLI11) and [Appveyor](https://ci.appveyor.com/project/HenrySchreiner/cli11), and is being included in the [GooFit GPU fitting framework](https://GooFit.github.io). It was inspired by [`plumbum.cli`](http://plumbum.readthedocs.io/en/latest/) for Python. It has both a user friendly introduction here, as well as [API documentation](https://henryiii.github.io/CLI11/index.html) generated by Travis. It is tested on [Travis](https://travis-ci.org/henryiii/CLI11) and [AppVeyor](https://ci.appveyor.com/project/HenrySchreiner/cli11), and is being included in the [GooFit GPU fitting framework](https://GooFit.github.io). It was inspired by [`plumbum.cli`](http://plumbum.readthedocs.io/en/latest/) for Python. It has both a user friendly introduction here, as well as [API documentation](https://henryiii.github.io/CLI11/index.html) generated by Travis.
### Why write another CLI parser? ### Why write another CLI parser?
@ -16,19 +16,20 @@ An acceptable CLI parser library should be all of the following:
* Short Syntax: This is one of the main points of 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. * Short Syntax: This is one of the main points of 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.
* C++11 or better: Should work with GCC 4.7+ (such as GCC 4.8 on CentOS 7) or above, or Clang 3.5+, or MSVC 2015+. (Note: for CLI11, Clang 3.4 only fails because of tests, googlemock does not support it.) * C++11 or better: Should work with GCC 4.7+ (such as GCC 4.8 on CentOS 7) or above, or Clang 3.5+, or MSVC 2015+. (Note: for CLI11, Clang 3.4 only fails because of tests, googlemock does not support it.)
* Work on Linux, macOS, and Windows. * Work on Linux, macOS, and Windows.
* Well tested using Travis (Linux and macOS) and [Appveyor](https://ci.appveyor.com/project/HenrySchreiner/cli11) (Windows). * Well tested using [Travis](https://travis-ci.org/henryiii/CLI11) (Linux and macOS) and [AppVeyor](https://ci.appveyor.com/project/HenrySchreiner/cli11) (Windows).
* Clear help printing. * Clear help printing.
* Standard shell idioms supported naturally, like grouping flags, a positional separator, etc. * Standard shell idioms supported naturally, like grouping flags, a positional separator, etc.
* Easy to execute, with help, parse errors, etc. providing correct exit and details. * Easy to execute, with help, parse errors, etc. providing correct exit and details.
* Easy to extend as part of a framework that provides "applications" to users. * Easy to extend as part of a framework that provides "applications" to users.
* Usable subcommand syntax, with support for multiple subcommands, nested subcommands, and optional fallthrough (explained later). * Usable subcommand syntax, with support for multiple subcommands, nested subcommands, and optional fallthrough (explained later).
* Ability to add a configuration file (`ini` format).
* Produce real values that can be used directly in code, not something you have pay compute time to look up, for HPC applications. * Produce real values that can be used directly in code, not something you have pay compute time to look up, for HPC applications.
The major CLI parsers for C++ include: The major CLI parsers for C++ include:
* [Boost Program Options](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html): 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. * [Boost Program Options](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html): 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.
* [The Lean Mean C++ Option Parser](http://optionparser.sourceforge.net): 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. * [The Lean Mean C++ Option Parser](http://optionparser.sourceforge.net): 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.
* [TCLAP](http://tclap.sourceforge.net): 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. Produced wrapped values. * [TCLAP](http://tclap.sourceforge.net): 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.
* [Cxxopts](https://github.com/jarro2783/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. * [Cxxopts](https://github.com/jarro2783/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.
So, this library was designed to provide a great syntax, good compiler compatibility, and minimal installation fuss. So, this library was designed to provide a great syntax, good compiler compatibility, and minimal installation fuss.
@ -48,8 +49,8 @@ See the [changelog](./CHANGELOG.md) or [GitHub releases](https://github.com/henr
As you probably have guessed, the list of features above are all covered by this library. There are some other features that are intentionally not supported by this library: As you probably have guessed, the list of features above are all covered by this library. There are some other features that are intentionally not supported by this library:
* Non-standard variations on syntax, like `-long` options. This is non-standard and should be avoided, so that is enforced by this library. * Non-standard variations on syntax, like `-long` options. This is non-standard and should be avoided, so that is enforced by this library.
* Completion of partial options, such as Python's `argparse` supplies for incomplete arguments. It's better not to guess. * 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 design flaw.
* In C++14, you could have a set of `callback` methods (tested in branch). Not deemed worth having a C++14 variation on API. * In C++14, you could have a set of `callback` methods (tested in a branch). Not deemed worth having a C++14 variation on API and removed.
* Autocomplete: This might eventually be added to both Plumbum and CLI11, but it is not supported yet. * Autocomplete: This might eventually be added to both Plumbum and CLI11, but it is not supported yet.