From f27f6f207007a45e9c6a55f089c67d9826ba1dbd Mon Sep 17 00:00:00 2001 From: Henry Schreiner Date: Sat, 17 Jul 2021 15:05:18 -0400 Subject: [PATCH] docs: fix some Codacity recommendations (#622) --- .github/CONTRIBUTING.md | 10 ++-- README.md | 96 ++++++++++++++++++------------------- book/README.md | 22 ++++----- book/chapters/flags.md | 2 +- book/chapters/formatting.md | 2 +- book/chapters/options.md | 9 +++- tests/HelpTest.cpp | 1 + tests/HelpersTest.cpp | 4 +- 8 files changed, 76 insertions(+), 70 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index c634a62b..3b656b14 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -12,7 +12,7 @@ Make sure any new functions you add are are: In general, make sure the addition is well thought out and does not increase the complexity of CLI11 needlessly. -## Things you should know: +## Things you should know * Once you make the PR, tests will run to make sure your code works on all supported platforms * The test coverage is also measured, and that should remain 100% @@ -31,7 +31,7 @@ python3 -m pip install pre-commit Then, you can run it on the items you've added to your staging area, or all files: -``` +```bash pre-commit run # OR pre-commit run --all-files @@ -75,8 +75,8 @@ Steps: * Update changelog if needed * Update the version in `.appveyor.yml` and `include/CLI/Version.hpp`. * Find and replace in README: - * Replace " 🆕" and "🆕 " with "" (ignores the description line) - * Check for `\/\/$` (vi syntax) to catch leftover `// 🆕` - * Replace "🚧" with "🆕" (manually ignore the description line) + * Replace " 🆕" and "🆕 " with "" (ignores the description line) + * Check for `\/\/$` (vi syntax) to catch leftover `// 🆕` + * Replace "🚧" with "🆕" (manually ignore the description line) * Make a release in the GitHub UI, use a name such as "Version X.Y(.Z): Title" * Currently, the release action wipes the title after you release, so remember to edit the title back to the original name after the `CLI11.hpp` file gets uploaded. diff --git a/README.md b/README.md index 75137d63..c870f0fe 100644 --- a/README.md +++ b/README.md @@ -25,33 +25,33 @@ CLI11 is a command line parser for C++11 and beyond that provides a rich feature ## Table of Contents - [Background](#background) - - [Introduction](#introduction) - - [Why write another CLI parser?](#why-write-another-cli-parser) - - [Other parsers](#other-parsers) - - [Features not supported by this library](#features-not-supported-by-this-library) + - [Introduction](#introduction) + - [Why write another CLI parser?](#why-write-another-cli-parser) + - [Other parsers](#other-parsers) + - [Features not supported by this library](#features-not-supported-by-this-library) - [Install](#install) - [Usage](#usage) - - [Adding options](#adding-options) - - [Option types](#option-types) - - [Example](#example) - - [Option options](#option-options) - - [Validators](#validators) - - [Transforming Validators](#transforming-validators) - - [Validator operations](#validator-operations) - - [Custom Validators](#custom-validators) - - [Querying Validators](#querying-validators) - - [Getting Results](#getting-results) - - [Subcommands](#subcommands) - - [Subcommand options](#subcommand-options) - - [Option groups](#option-groups) - - [Callbacks](#callbacks) - - [Configuration file](#configuration-file) - - [Inheriting defaults](#inheriting-defaults) - - [Formatting](#formatting) - - [Subclassing](#subclassing) - - [How it works](#how-it-works) - - [Utilities](#utilities) - - [Other libraries](#other-libraries) + - [Adding options](#adding-options) + - [Option types](#option-types) + - [Example](#example) + - [Option options](#option-options) + - [Validators](#validators) + - [Transforming Validators](#transforming-validators) + - [Validator operations](#validator-operations) + - [Custom Validators](#custom-validators) + - [Querying Validators](#querying-validators) + - [Getting Results](#getting-results) + - [Subcommands](#subcommands) + - [Subcommand options](#subcommand-options) + - [Option groups](#option-groups) + - [Callbacks](#callbacks) + - [Configuration file](#configuration-file) + - [Inheriting defaults](#inheriting-defaults) + - [Formatting](#formatting) + - [Subclassing](#subclassing) + - [How it works](#how-it-works) + - [Utilities](#utilities) + - [Other libraries](#other-libraries) - [API](#api) - [Examples](#Examples) - [Contribute](#contribute) @@ -879,29 +879,29 @@ The API is [documented here][api-docs]. Also see the [CLI11 tutorial GitBook][gi Several short examples of different features are included in the repository. A brief description of each is included here - - [callback_passthrough](https://github.com/CLIUtils/CLI11/blob/master/examples/callback_passthrough.cpp): Example of directly passing remaining arguments through to a callback function which generates a CLI11 application based on existing arguments. - - [custom_parse](https://github.com/CLIUtils/CLI11/blob/master/examples/custom_parse.cpp): Based on [Issue #566](https://github.com/CLIUtils/CLI11/issues/566), example of custom parser - - [digit_args](https://github.com/CLIUtils/CLI11/blob/master/examples/digit_args.cpp): Based on [Issue #123](https://github.com/CLIUtils/CLI11/issues/123), uses digit flags to pass a value - - [enum](https://github.com/CLIUtils/CLI11/blob/master/examples/enum.cpp): Using enumerations in an option, and the use of [CheckedTransformer](#transforming-validators) - - [enum_ostream](https://github.com/CLIUtils/CLI11/blob/master/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. - - [formatter](https://github.com/CLIUtils/CLI11/blob/master/examples/formatter.cpp): Illustrating usage of a custom formatter - - [groups](https://github.com/CLIUtils/CLI11/blob/master/examples/groups.cpp): Example using groups of options for help grouping and a the timer helper class - - [inter_argument_order](https://github.com/CLIUtils/CLI11/blob/master/examples/inter_argument_order.cpp): An app to practice mixing unlimited arguments, but still recover the original order. - - [json](https://github.com/CLIUtils/CLI11/blob/master/examples/json.cpp): Using JSON as a config file parser - - [modhelp](https://github.com/CLIUtils/CLI11/blob/master/examples/modhelp.cpp): How to modify the help flag to do something other than default - - [nested](https://github.com/CLIUtils/CLI11/blob/master/examples/nested.cpp): Nested subcommands - - [option_groups](https://github.com/CLIUtils/CLI11/blob/master/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 - - [positional_arity](https://github.com/CLIUtils/CLI11/blob/master/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) - - [positional_validation](https://github.com/CLIUtils/CLI11/blob/master/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) - - [prefix_command](https://github.com/CLIUtils/CLI11/blob/master/examples/prefix_command.cpp): illustrating use of the `prefix_command` flag. - - [ranges](https://github.com/CLIUtils/CLI11/blob/master/examples/ranges.cpp): App to demonstrate exclusionary option groups based on [Issue #88](https://github.com/CLIUtils/CLI11/issues/88) - - [shapes](https://github.com/CLIUtils/CLI11/blob/master/examples/shapes.cpp): illustrating how to set up repeated subcommands Based on [gitter discussion](https://gitter.im/CLI11gitter/Lobby?at=5c7af6b965ffa019ea788cd5) - - [simple](https://github.com/CLIUtils/CLI11/blob/master/examples/simple.cpp): a simple example of how to set up a CLI11 Application with different flags and options - - [subcom_help](https://github.com/CLIUtils/CLI11/blob/master/examples/subcom_help.cpp): configuring help for subcommands - - [subcom_partitioned](https://github.com/CLIUtils/CLI11/blob/master/examples/subcom_partitioned.cpp): Example with a timer and subcommands generated separately and added to the main app later. - - [subcommands](https://github.com/CLIUtils/CLI11/blob/master/examples/subcommands.cpp): Short example of subcommands - - [validators](https://github.com/CLIUtils/CLI11/blob/master/examples/validators.cpp): Example illustrating use of validators +- [callback_passthrough](https://github.com/CLIUtils/CLI11/blob/master/examples/callback_passthrough.cpp): Example of directly passing remaining arguments through to a callback function which generates a CLI11 application based on existing arguments. +- [custom_parse](https://github.com/CLIUtils/CLI11/blob/master/examples/custom_parse.cpp): Based on [Issue #566](https://github.com/CLIUtils/CLI11/issues/566), example of custom parser +- [digit_args](https://github.com/CLIUtils/CLI11/blob/master/examples/digit_args.cpp): Based on [Issue #123](https://github.com/CLIUtils/CLI11/issues/123), uses digit flags to pass a value +- [enum](https://github.com/CLIUtils/CLI11/blob/master/examples/enum.cpp): Using enumerations in an option, and the use of [CheckedTransformer](#transforming-validators) +- [enum_ostream](https://github.com/CLIUtils/CLI11/blob/master/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. +- [formatter](https://github.com/CLIUtils/CLI11/blob/master/examples/formatter.cpp): Illustrating usage of a custom formatter +- [groups](https://github.com/CLIUtils/CLI11/blob/master/examples/groups.cpp): Example using groups of options for help grouping and a the timer helper class +- [inter_argument_order](https://github.com/CLIUtils/CLI11/blob/master/examples/inter_argument_order.cpp): An app to practice mixing unlimited arguments, but still recover the original order. +- [json](https://github.com/CLIUtils/CLI11/blob/master/examples/json.cpp): Using JSON as a config file parser +- [modhelp](https://github.com/CLIUtils/CLI11/blob/master/examples/modhelp.cpp): How to modify the help flag to do something other than default +- [nested](https://github.com/CLIUtils/CLI11/blob/master/examples/nested.cpp): Nested subcommands +- [option_groups](https://github.com/CLIUtils/CLI11/blob/master/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 +- [positional_arity](https://github.com/CLIUtils/CLI11/blob/master/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) +- [positional_validation](https://github.com/CLIUtils/CLI11/blob/master/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) +- [prefix_command](https://github.com/CLIUtils/CLI11/blob/master/examples/prefix_command.cpp): illustrating use of the `prefix_command` flag. +- [ranges](https://github.com/CLIUtils/CLI11/blob/master/examples/ranges.cpp): App to demonstrate exclusionary option groups based on [Issue #88](https://github.com/CLIUtils/CLI11/issues/88) +- [shapes](https://github.com/CLIUtils/CLI11/blob/master/examples/shapes.cpp): illustrating how to set up repeated subcommands Based on [gitter discussion](https://gitter.im/CLI11gitter/Lobby?at=5c7af6b965ffa019ea788cd5) +- [simple](https://github.com/CLIUtils/CLI11/blob/master/examples/simple.cpp): a simple example of how to set up a CLI11 Application with different flags and options +- [subcom_help](https://github.com/CLIUtils/CLI11/blob/master/examples/subcom_help.cpp): configuring help for subcommands +- [subcom_partitioned](https://github.com/CLIUtils/CLI11/blob/master/examples/subcom_partitioned.cpp): Example with a timer and subcommands generated separately and added to the main app later. +- [subcommands](https://github.com/CLIUtils/CLI11/blob/master/examples/subcommands.cpp): Short example of subcommands +- [validators](https://github.com/CLIUtils/CLI11/blob/master/examples/validators.cpp): Example illustrating use of validators ## Contribute diff --git a/book/README.md b/book/README.md index ee69437f..a10964b9 100644 --- a/book/README.md +++ b/book/README.md @@ -51,16 +51,16 @@ You can use subcommands, as well. Subcommands support callback lambda functions Reading/producing `.ini` files for configuration is also supported, as is using environment variables as input. The base `App` can be subclassed and customized for use in a toolkit (like [GooFit][]). All the standard shell idioms, like `--`, work as well. -CLI11 was developed at the [University of Cincinnati] in support of the [GooFit][] library under [NSF Award 1414736][NSF 1414736]. It was featured in a [DIANA/HEP] meeting at CERN. Please give it a try! Feedback is always welcome. +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]: http://diana-hep.org -[CLI11]: https://github.com/CLIUtils/CLI11 -[CLI11Tutorial]: https://cliutils.github.io/CLI11/book +[goofit]: https://github.com/GooFit/GooFit +[diana/hep]: http://diana-hep.org +[cli11]: https://github.com/CLIUtils/CLI11 +[cli11tutoriaL]: https://cliutils.github.io/CLI11/book [releases]: https://github.com/CLIUtils/CLI11/releases -[API docs]: https://cliutils.github.io/CLI11 -[README]: https://github.com/CLIUtils/CLI11/blob/master/README.md -[NSF 1414736]: https://nsf.gov/awardsearch/showAward?AWD_ID=1414736 -[University of Cincinnati]: http://www.uc.edu -[Plumbum]: http://plumbum.readthedocs.io/en/latest/ -[Click]: https://click.palletsprojects.com/ +[api docs]: https://cliutils.github.io/CLI11 +[readme]: https://github.com/CLIUtils/CLI11/blob/master/README.md +[nsf 1414736]: https://nsf.gov/awardsearch/showAward?AWD_ID=1414736 +[university of cincinnati]: http://www.uc.edu +[plumbum]: http://plumbum.readthedocs.io/en/latest/ +[click]: https://click.palletsprojects.com/ diff --git a/book/chapters/flags.md b/book/chapters/flags.md index 76c47da7..c14b2421 100644 --- a/book/chapters/flags.md +++ b/book/chapters/flags.md @@ -65,7 +65,7 @@ After parsing, you can use `my_flag->count()` to count the number of times this If you want to define a callback that runs when you make a flag, you can use `add_flag_function` (C++11 or newer) or `add_flag` (C++14 or newer only) to add a callback function. The function should have the signature `void(std::size_t)`. This could be useful for a version printout, etc. -``` +```cpp auto callback = [](int count){std::cout << "This was called " << count << " times";}; app.add_flag_function("-c", callback, "Optional description"); ``` diff --git a/book/chapters/formatting.md b/book/chapters/formatting.md index 8acbae75..01c35f45 100644 --- a/book/chapters/formatting.md +++ b/book/chapters/formatting.md @@ -41,7 +41,7 @@ Look at the class definitions in `FormatterFwd.hpp` or the method definitions in This is a normal printout, with `<>` indicating the methods used to produce each line. -``` +```text diff --git a/book/chapters/options.md b/book/chapters/options.md index ba1eed7a..401fa915 100644 --- a/book/chapters/options.md +++ b/book/chapters/options.md @@ -72,23 +72,28 @@ Vectors will be replaced by the parsed content if the option is given on the com A definition of a container for purposes of CLI11 is a type with a `end()`, `insert(...)`, `clear()` and `value_type` definitions. This includes `vector`, `set`, `deque`, `list`, `forward_iist`, `map`, `unordered_map` and a few others from the standard library, and many other containers from the boost library. -### containers of containers +### Containers of containers Containers of containers are also supported. + ```cpp std::vector> int_vec; app.add_option("--vec", int_vec, "My vector of vectors option"); ``` + CLI11 inserts a separator sequence at the start of each argument call to separate the vectors. So unless the separators are injected as part of the command line each call of the option on the command line will result in a separate element of the outer vector. This can be manually controlled via `inject_separator(true|false)` but in nearly all cases this should be left to the defaults. To insert of a separator from the command line add a `%%` where the separation should occur. -``` + +```bash cmd --vec_of_vec 1 2 3 4 %% 1 2 ``` would then result in a container of size 2 with the first element containing 4 values and the second 2. This separator is also the only way to get values into something like + ```cpp std::pair,std::vector> two_vecs; app.add_option("--vec", two_vecs, "pair of vectors"); ``` + without calling the argument twice. Further levels of nesting containers should compile but intermediate layers will only have a single element in the container, so is probably not that useful. diff --git a/tests/HelpTest.cpp b/tests/HelpTest.cpp index 276bf916..cb8c81ab 100644 --- a/tests/HelpTest.cpp +++ b/tests/HelpTest.cpp @@ -1175,6 +1175,7 @@ TEST_CASE("THelp: ChangingDefaultsWithAutoCapture", "[help]") { CHECK(x[0] == 1); app.add_option("-q,--quick", x); x = {3, 4}; + CHECK(x[0] == 3); std::string help = app.help(); diff --git a/tests/HelpersTest.cpp b/tests/HelpersTest.cpp index 5fc2275c..5d6c1712 100644 --- a/tests/HelpersTest.cpp +++ b/tests/HelpersTest.cpp @@ -1145,8 +1145,8 @@ TEST_CASE("Types: LexicalConversionDoubleTuple", "[helpers]") { CHECK(std::get<0>(x) == Approx(9.12)); CLI::results_t bad_input = {"hello"}; - res = CLI::detail::lexical_conversion(input, x); - CHECK(res); + res = CLI::detail::lexical_conversion(bad_input, x); + CHECK_FALSE(res); } TEST_CASE("Types: LexicalConversionVectorDouble", "[helpers]") {