mirror of
https://github.com/CLIUtils/CLI11.git
synced 2025-05-02 05:33:53 +00:00
fix some doc and error strings (#899)
Update some doc strings and error output for clarity --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Philip Top
GitHub
parent
f07a8cc6fb
commit
985a19f386
45
README.md
45
README.md
@ -24,6 +24,8 @@ set with a simple and intuitive interface.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [CLI11: Command line parser for C++11](#cli11-command-line-parser-for-c11)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Background](#background)
|
||||
- [Introduction](#introduction)
|
||||
- [Why write another CLI parser?](#why-write-another-cli-parser)
|
||||
@ -40,21 +42,23 @@ set with a simple and intuitive interface.
|
||||
- [Validator operations](#validator-operations)
|
||||
- [Custom Validators](#custom-validators)
|
||||
- [Querying Validators](#querying-validators)
|
||||
- [Getting Results](#getting-results)
|
||||
- [Getting results](#getting-results)
|
||||
- [Subcommands](#subcommands)
|
||||
- [Subcommand options](#subcommand-options)
|
||||
- [Option groups](#option-groups)
|
||||
- [Callbacks](#callbacks)
|
||||
- [Option groups](#option-groups)
|
||||
- [Configuration file](#configuration-file)
|
||||
- [Inheriting defaults](#inheriting-defaults)
|
||||
- [Formatting](#formatting)
|
||||
- [Subclassing](#subclassing)
|
||||
- [How it works](#how-it-works)
|
||||
- [Example](#example-1)
|
||||
- [Unicode support](#unicode-support)
|
||||
- [Note on using Unicode paths](#note-on-using-unicode-paths)
|
||||
- [Utilities](#utilities)
|
||||
- [Other libraries](#other-libraries)
|
||||
- [API](#api)
|
||||
- [Examples](#Examples)
|
||||
- [Examples](#examples)
|
||||
- [Contribute](#contribute)
|
||||
- [License](#license)
|
||||
|
||||
@ -224,7 +228,7 @@ include(FetchContent)
|
||||
FetchContent_Declare(
|
||||
cli11
|
||||
GIT_REPOSITORY https://github.com/CLIUtils/CLI11
|
||||
GIT_TAG v2.2.0
|
||||
GIT_TAG v2.3.2
|
||||
)
|
||||
|
||||
FetchContent_MakeAvailable(cli11)
|
||||
@ -265,6 +269,10 @@ In 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.
|
||||
|
||||
If building with WASI it is necessary to add the flag
|
||||
`-lc-printscan-long-double` to the build to allow long double support. See #841
|
||||
for more details.
|
||||
|
||||
</p></details>
|
||||
</br>
|
||||
|
||||
@ -287,6 +295,9 @@ int main() {
|
||||
}
|
||||
```
|
||||
|
||||
The 🚧 `CLI11_PARSE(app)` is only available in main currently and not in a
|
||||
release.
|
||||
|
||||
<details><summary>Note: If you don't like macros, this is what that macro expands to: (click to expand)</summary><p>
|
||||
|
||||
```cpp
|
||||
@ -309,7 +320,8 @@ interfere.
|
||||
<details><summary>Note: Why are argc and argv not used? (click to expand)</summary><p>
|
||||
|
||||
`argc` and `argv` may contain incorrect information on Windows when unicode text
|
||||
is passed in. Check out a section on [unicode support](#unicode-support) below.
|
||||
is passed in. Check out a section on [unicode support](#unicode-support)🚧
|
||||
below.
|
||||
|
||||
If this is not a concern, you can explicitly pass `argc` and `argv` from main or
|
||||
from an external preprocessor of CLI arguments to `parse`:
|
||||
@ -514,8 +526,8 @@ Before parsing, you can set the following options:
|
||||
- `->envname(name)`: Gets the value from the environment if present and not
|
||||
passed on the command line.
|
||||
- `->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).
|
||||
options. Defaults to `"Options"`. Options given an empty string will not show
|
||||
up in the help print (hidden).
|
||||
- `->ignore_case()`: Ignore the case on the command line (also works on
|
||||
subcommands, does not affect arguments).
|
||||
- `->ignore_underscore()`: Ignore any underscores in the options names (also
|
||||
@ -901,12 +913,15 @@ not used in performance critical code:
|
||||
|
||||
### Subcommands
|
||||
|
||||
Subcommands 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
|
||||
Subcommands are keywords that invoke a new set of options and features. For
|
||||
example, the `git` command has a long series of subcommands, like `add` and
|
||||
`commit`. Each can have its own options and implementations. Subcommands are
|
||||
supported in CLI11, 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`).
|
||||
|
||||
@ -1109,8 +1124,8 @@ option_groups. These are:
|
||||
returns a pointer to the created option. Expands subcommands.
|
||||
- `.failure_message(func)`: Set the failure message function. Two provided:
|
||||
`CLI::FailureMessage::help` and `CLI::FailureMessage::simple` (the default).
|
||||
- `.group(name)`: Set a group name, defaults to `"Subcommands"`. Setting `""`
|
||||
will be hide the subcommand.
|
||||
- `.group(name)`: Set a group name, defaults to `"Subcommands"`. Setting an
|
||||
empty string for the name will be hide the subcommand.
|
||||
- `[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
|
||||
|
||||
@ -215,7 +215,7 @@ that to add option modifiers. A full listing of the option modifiers:
|
||||
| `->needs(opt)` | This option requires another option to also be present, opt is an `Option` pointer or a string with the name of the option. Can be removed with `->remove_needs(opt)` |
|
||||
| `->excludes(opt)` | This option cannot be given with `opt` present, opt is an `Option` pointer or a string with the name of the option. Can be removed with `->remove_excludes(opt)` |
|
||||
| `->envname(name)` | Gets the value from the environment if present and not passed on the command line. |
|
||||
| `->group(name)` | The help group to put the option in. No effect for positional options. Defaults to `"Options"`. `"Hidden"` will not show up in the help print. |
|
||||
| `->group(name)` | The help group to put the option in. No effect for positional options. Defaults to `"Options"`. Options given an empty string for the group name will not show up in the help print. |
|
||||
| `->description(string)` | Set/change the description |
|
||||
| `->ignore_case()` | Ignore the case on the command line (also works on subcommands, does not affect arguments). |
|
||||
| `->ignore_underscore()` | Ignore any underscores on the command line (also works on subcommands, does not affect arguments). |
|
||||
|
||||
@ -123,6 +123,9 @@ class BadNameString : public ConstructionError {
|
||||
CLI11_ERROR_DEF(ConstructionError, BadNameString)
|
||||
CLI11_ERROR_SIMPLE(BadNameString)
|
||||
static BadNameString OneCharName(std::string name) { return BadNameString("Invalid one char name: " + name); }
|
||||
static BadNameString MissingDash(std::string name) {
|
||||
return BadNameString("Long names strings require 2 dashes " + name);
|
||||
}
|
||||
static BadNameString BadLongName(std::string name) { return BadNameString("Bad long name: " + name); }
|
||||
static BadNameString DashesOnly(std::string name) {
|
||||
return BadNameString("Must have a name, not just dashes: " + name);
|
||||
|
||||
@ -114,6 +114,8 @@ get_names(const std::vector<std::string> &input) {
|
||||
if(name.length() > 1 && name[0] == '-' && name[1] != '-') {
|
||||
if(name.length() == 2 && valid_first_char(name[1]))
|
||||
short_names.emplace_back(1, name[1]);
|
||||
else if(name.length() > 2)
|
||||
throw BadNameString::MissingDash(name);
|
||||
else
|
||||
throw BadNameString::OneCharName(name);
|
||||
} else if(name.length() > 2 && name.substr(0, 2) == "--") {
|
||||
|
||||
@ -641,6 +641,28 @@ TEST_CASE_METHOD(TApp, "StrangeOptionNames", "[app]") {
|
||||
CHECK(app["--{}"]->as<int>() == 5);
|
||||
}
|
||||
|
||||
TEST_CASE_METHOD(TApp, "singledash", "[app]") {
|
||||
app.add_option("-t");
|
||||
try {
|
||||
app.add_option("-test");
|
||||
} catch(const CLI::BadNameString &e) {
|
||||
std::string str = e.what();
|
||||
CHECK_THAT(str, Contains("2 dashes"));
|
||||
CHECK_THAT(str, Contains("-test"));
|
||||
} catch(...) {
|
||||
CHECK(false);
|
||||
}
|
||||
try {
|
||||
app.add_option("-!");
|
||||
} catch(const CLI::BadNameString &e) {
|
||||
std::string str = e.what();
|
||||
CHECK_THAT(str, Contains("one char"));
|
||||
CHECK_THAT(str, Contains("-!"));
|
||||
} catch(...) {
|
||||
CHECK(false);
|
||||
}
|
||||
}
|
||||
|
||||
TEST_CASE_METHOD(TApp, "FlagLikeOption", "[app]") {
|
||||
bool val{false};
|
||||
auto *opt = app.add_option("--flag", val)->type_size(0)->default_str("true");
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user