From 4160d259d961cd393fd8d67590a8c7d210207348 Mon Sep 17 00:00:00 2001 From: Philip Top Date: Thu, 27 Feb 2025 04:25:31 -0800 Subject: [PATCH] update version and changelog for 2.5 release (#1121) update readme, changelog, and version for 2.5 release --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Henry Schreiner --- CHANGELOG.md | 71 +++++++++++++++++++++++++++++++++++++++-- README.md | 52 ++++++++++++++++-------------- include/CLI/Version.hpp | 6 ++-- 3 files changed, 100 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6c52c4f8..e3baf5c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,8 +2,75 @@ ## Unreleased -- add mechanism to allow option groups to be hidden and all options be - considered part of the parent for help display +## Version 2.5: Help Formatter + +This version add a new formatter with improved control capabilities and output +aligned with standards for help output. It also add a modifier to enable use of +non-standard option names. Along with several bug fixes for edge cases in string +and config file parsing. + +- Better help formatter [#866][], this better aligns the help generation with + UNIX standard and allows use in help2man. [#1093][] +- Add mechanism to allow option groups to be hidden and all options be + considered part of the parent for help display [#1039][] +- Add a modifier to allow non-standard single flag option names such as + `-option`. [#1078][] +- Add modifier for subcommands to disable fallthrough which can resolve some + issues with positional arguments [#1073][] +- Add some polish to config file output removing some unnecessary output and add + modifier to control output of default values [#1075][] +- Add the ability to specify pair/tuple defaults and improved parsing [#1081][] +- Bugfix: Take the configurability of an option name into account when + determining naming conflicts [#1049][] +- Bugfix: Fix an issue where an extra subcommand header was being printed in the + output [#1058][] +- Bugfix: Add additional fuzzing tests and fixes for a bug in escape string + processing, and resolve inconsistencies in the handing of `{}` between command + line parsing and config file parsing. [#1060][] +- Bugfix: Improve handling of some ambiguities in vector input processing for + config files, specifically in the case of vector of vector inputs. [#1069][] +- Bugfix: Fix an issue in the handling of uint8_t enums, and some issues related + to single element tuples [#1087][] +- Bugfix: Fix an issue with binary strings containing a `\x` [#1097][] +- Bugfix: Move the help generation priority so it triggers before config file + processing [#1106][] +- Bugfix: Fixed an issue where max/min on positionals was not being respected + and optional positionals were being ignored [#1108][] +- Bugfix: Fix an issue with strings which started and ended with brackets being + misinterpreted as vectors. The parsing now has special handling of strings + which start with `[[` [#1110][] +- Bugfix: Fix some macros for support in C++26 related to wide string parsing + [#1113][] +- Bugfix: Allow trailing spaces on numeric string conversions [#1115][] +- Docs: Update pymod.find_installation to find python in meson.build [#1076][] +- Docs: Add example for transform validators [#689][] +- Docs: Fix several spelling mistakes [#1101][] +- Backend: Update copyright dates to 2025 [#1112][] +- Backend: Update CMAKE minimum version to 3.10 [#1084][] + +[#1039]: https://github.com/CLIUtils/CLI11/pull/1039 +[#1049]: https://github.com/CLIUtils/CLI11/pull/1049 +[#1058]: https://github.com/CLIUtils/CLI11/pull/1058 +[#1060]: https://github.com/CLIUtils/CLI11/pull/1060 +[#1069]: https://github.com/CLIUtils/CLI11/pull/1069 +[#866]: https://github.com/CLIUtils/CLI11/pull/866 +[#1073]: https://github.com/CLIUtils/CLI11/pull/1073 +[#1075]: https://github.com/CLIUtils/CLI11/pull/1075 +[#689]: https://github.com/CLIUtils/CLI11/pull/689 +[#1076]: https://github.com/CLIUtils/CLI11/pull/1076 +[#1078]: https://github.com/CLIUtils/CLI11/pull/1078 +[#1081]: https://github.com/CLIUtils/CLI11/pull/1081 +[#1084]: https://github.com/CLIUtils/CLI11/pull/1084 +[#1087]: https://github.com/CLIUtils/CLI11/pull/1087 +[#1093]: https://github.com/CLIUtils/CLI11/pull/1093 +[#1097]: https://github.com/CLIUtils/CLI11/pull/1097 +[#1101]: https://github.com/CLIUtils/CLI11/pull/1101 +[#1106]: https://github.com/CLIUtils/CLI11/pull/1106 +[#1108]: https://github.com/CLIUtils/CLI11/pull/1108 +[#1110]: https://github.com/CLIUtils/CLI11/pull/1110 +[#1112]: https://github.com/CLIUtils/CLI11/pull/1112 +[#1113]: https://github.com/CLIUtils/CLI11/pull/1113 +[#1115]: https://github.com/CLIUtils/CLI11/pull/1115 ## Version 2.4: Unicode and TOML support diff --git a/README.md b/README.md index c8b5b52b..1522e25d 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,9 @@ this library: option to disable it). - Autocomplete: This might eventually be added to both Plumbum and CLI11, but it is not supported yet. +- While not recommended, CLI11 does now support non standard option names such + as `-option`. 🆕. This is enabled through `allow_non_standard_option_names()` + modifier on an app. ## Install @@ -203,9 +206,8 @@ int main(int argc, char** argv) { } ``` -For more information about 🆕`ensure_utf8` the section on -[Unicode support](#unicode-support) below. The 🆕`ensure_utf8` function is only -available in main currently and not in a release. +For more information about `ensure_utf8` the section on +[Unicode support](#unicode-support) below.
Note: If you don't like macros, this is what that macro expands to: (click to expand)

@@ -415,7 +417,7 @@ Before parsing, you can set the following options: option. Options can be removed from the excludes list with `->remove_excludes(opt)` - `->envname(name)`: Gets the value from the environment if present and not - passed on the command line. 🆕 The value must also pass any validators to be + passed on the command line. The value must also pass any validators to be used. - `->group(name)`: The help group to put the option in. No effect for positional options. Defaults to `"Options"`. Options given an empty string will not show @@ -451,7 +453,7 @@ Before parsing, you can set the following options: are `CLI::MultiOptionPolicy::Throw`, `CLI::MultiOptionPolicy::Throw`, `CLI::MultiOptionPolicy::TakeLast`, `CLI::MultiOptionPolicy::TakeFirst`, `CLI::MultiOptionPolicy::Join`, `CLI::MultiOptionPolicy::TakeAll`, - `CLI::MultiOptionPolicy::Sum`, and `CLI::MultiOptionPolicy::Reverse` 🆕. + `CLI::MultiOptionPolicy::Sum`, and `CLI::MultiOptionPolicy::Reverse`. - `->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 @@ -701,8 +703,8 @@ filters on the key values is performed. `CLI::FileOnDefaultPath(default_path, false)`. This allows multiple paths to be chained using multiple transform calls. -- `CLI::EscapedString`: 🆕 can be used to process an escaped string. The - processing is equivalent to that used for TOML config files, see +- `CLI::EscapedString`: can be used to process an escaped string. The processing + is equivalent to that used for TOML config files, see [TOML strings](https://toml.io/en/v1.0.0#string). With 2 notable exceptions. \` can also be used as a literal string notation, and it also allows binary string notation see @@ -859,7 +861,9 @@ 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. +subcommand have been parsed, and can be triggered multiple times. Note that the +`parse_complete_callback()` is executed prior to processing any config files. +The `final_callback()` is executed after config file processing. Subcommands may also have an empty name either by calling `add_subcommand` with an empty string for the name or with no arguments. Nameless subcommands function @@ -873,7 +877,7 @@ 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. -🆕 Options or flags in a subcommand may be directly specified using dot notation +Options or flags in a subcommand may be directly specified using dot notation - `--subcommand.long=val` (long subcommand option) - `--subcommand.long val` (long subcommand option) @@ -885,8 +889,8 @@ through the `add_subcommand` method have the same restrictions as option names. The use of dot notation in this form is equivalent `--subcommand.long ` => `subcommand --long ++`. Nested subcommands also work `sub1.subsub` would trigger the subsub subcommand in `sub1`. This is equivalent to "sub1 subsub". -Quotes around the subcommand names are permitted 🆕 following the TOML standard -for such specification. This includes allowing escape sequences. For example +Quotes around the subcommand names are permitted following the TOML standard for +such specification. This includes allowing escape sequences. For example `"subcommand".'f'` or `"subcommand.with.dots".arg1 = value`. #### Subcommand options @@ -902,7 +906,7 @@ option_groups. These are: 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`. -- `.allow_non_standard_option_names()`:🚧 Allow specification of single `-` long +- `.allow_non_standard_option_names()`:🆕 Allow specification of single `-` long form option names. This is not recommended but is available to enable reworking of existing interfaces. If this modifier is enabled on an app or subcommand, options or flags can be specified like normal but instead of @@ -914,8 +918,8 @@ option_groups. These are: through" and be matched on a parent option. Subcommands by default 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. This can be disabled through `subcommand_fallthrough(false)` 🚧. -- `.subcommand_fallthrough()`: 🚧 Allow subcommands to "fall through" and be + subcommands. This can be disabled through `subcommand_fallthrough(false)` 🆕. +- `.subcommand_fallthrough()`: 🆕 Allow subcommands to "fall through" and be matched on a parent option. Disabling this prevents additional subcommands at the same level from being matched. It can be useful in certain circumstances where there might be ambiguity between subcommands and positionals. The @@ -1027,10 +1031,10 @@ option_groups. These are: the first unrecognized item. All subsequent arguments are placed in the remaining_arg list. It is ideal for allowing your app or subcommand to be a "prefix" to calling another app. -- `.usage(message)`: 🆕 Replace text to appear at the start of the help string +- `.usage(message)`: Replace text to appear at the start of the help string after description. -- `.usage(std::string())`: 🆕 Set a callback to generate a string that will - appear at the start of the help string after description. +- `.usage(std::string())`: Set a callback to generate a string that will appear + at the start of the help string after description. - `.footer(message)`: Set text to appear at the bottom of the help string. - `.footer(std::string())`: Set a callback to generate a string that will appear at the end of the help string. @@ -1113,8 +1117,8 @@ A subcommand is considered terminated when one of the following conditions are met. 1. There are no more arguments to process -2. Another subcommand is encountered that would not fit in an optional slot of - the subcommand +2. Another subcommand is encountered that would not fit in an optional + positional slot of the subcommand 3. The `positional_mark` (`--`) is encountered and there are no available positional slots in the subcommand. 4. The `subcommand_terminator` mark (`++`) is encountered @@ -1246,11 +1250,11 @@ 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. The config reader -can read most aspects of TOML files including strings both literal 🆕 and with -potential escape sequences 🆕, digit separators 🆕, and multi-line strings 🆕, -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: +can read most aspects of TOML files including strings both literal and with +potential escape sequences, digit separators, and multi-line strings, 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: ```toml # Comments are supported, using a # diff --git a/include/CLI/Version.hpp b/include/CLI/Version.hpp index 3427220d..25f8560d 100644 --- a/include/CLI/Version.hpp +++ b/include/CLI/Version.hpp @@ -11,8 +11,8 @@ // [CLI11:version_hpp:verbatim] #define CLI11_VERSION_MAJOR 2 -#define CLI11_VERSION_MINOR 4 -#define CLI11_VERSION_PATCH 2 -#define CLI11_VERSION "2.4.2" +#define CLI11_VERSION_MINOR 5 +#define CLI11_VERSION_PATCH 0 +#define CLI11_VERSION "2.5.0" // [CLI11:version_hpp:end]