diff --git a/CHANGELOG.md b/CHANGELOG.md index 4fc3ccdd1..c4e46ea65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,71 @@ # Changelog +## Version 2.4: Unicode and TOML support + +This version adds Unicode support, support for TOML standard including multiline +strings, digit separators, string escape sequences,and dot notation. An initial +round of a fuzzer was added to testing which has caught several bugs related to +config file processing, and a few other edge cases not previously observed. + +- Add Unicode support and bug fixes [#804][], [#923][], [#876][], [#848][], + [#832][], [#987][] +- Match TOML standard for string and numerical entries, multiline strings + [#968][], [#967][],[#964][], [#935][] +- Add validation for environmental variables [#926][] +- Add an escape string transform [#970][] +- Add A REVERSE multi-option policy to support multiple config files and other + applications [#918][] +- Add usage message replacement [#768][] +- Allow using dot notation for subcommand arguments such as `--sub1.field` + [#789][] +- Bugfix: Fuzzing tests and fixes [#930][], [#905][], [#874][], [#846][] +- Bugfix: Missing coverage tests [#928][] +- Bugfix: CMake package and package config tests and fixes [#916][] +- Bugfix: Support for Windows ARM compilation and tests [#913][], [#914][] +- Bugfix: Environmental variable checks in non-triggered subcommands [#904][] +- Bugfix: Environmental variables were not being correctly process by config + pointer [#891][] +- Bugfix: Undefined behavior in `sum_string_vector` [#893][] +- Bugfix: Warnings and updates for CUDA 11 support [#851][] +- Backend: Add tests for newer compilers (lost with Travis CI) [#972][] +- Backend: Increase minimum CMake to 3.5 [#898][] +- Backend: Remove integrated Conan support (provided now by Conan center) + [#853][] +- Tests: Support Catch2 Version 3 [#896][], [#980][] + +[#768]: https://github.com/CLIUtils/CLI11/pull/768 +[#789]: https://github.com/CLIUtils/CLI11/pull/789 +[#804]: https://github.com/CLIUtils/CLI11/pull/804 +[#832]: https://github.com/CLIUtils/CLI11/pull/832 +[#846]: https://github.com/CLIUtils/CLI11/pull/846 +[#848]: https://github.com/CLIUtils/CLI11/pull/848 +[#851]: https://github.com/CLIUtils/CLI11/pull/851 +[#853]: https://github.com/CLIUtils/CLI11/pull/853 +[#874]: https://github.com/CLIUtils/CLI11/pull/874 +[#876]: https://github.com/CLIUtils/CLI11/pull/876 +[#891]: https://github.com/CLIUtils/CLI11/pull/891 +[#893]: https://github.com/CLIUtils/CLI11/pull/893 +[#896]: https://github.com/CLIUtils/CLI11/pull/896 +[#898]: https://github.com/CLIUtils/CLI11/pull/898 +[#904]: https://github.com/CLIUtils/CLI11/pull/904 +[#905]: https://github.com/CLIUtils/CLI11/pull/905 +[#913]: https://github.com/CLIUtils/CLI11/pull/913 +[#914]: https://github.com/CLIUtils/CLI11/pull/914 +[#916]: https://github.com/CLIUtils/CLI11/pull/916 +[#918]: https://github.com/CLIUtils/CLI11/pull/918 +[#923]: https://github.com/CLIUtils/CLI11/pull/923 +[#926]: https://github.com/CLIUtils/CLI11/pull/926 +[#928]: https://github.com/CLIUtils/CLI11/pull/928 +[#930]: https://github.com/CLIUtils/CLI11/pull/930 +[#935]: https://github.com/CLIUtils/CLI11/pull/935 +[#964]: https://github.com/CLIUtils/CLI11/pull/964 +[#967]: https://github.com/CLIUtils/CLI11/pull/967 +[#968]: https://github.com/CLIUtils/CLI11/pull/968 +[#970]: https://github.com/CLIUtils/CLI11/pull/970 +[#972]: https://github.com/CLIUtils/CLI11/pull/972 +[#980]: https://github.com/CLIUtils/CLI11/pull/980 +[#987]: https://github.com/CLIUtils/CLI11/pull/987 + ## Version 2.3: Precompilation Support This version adds a pre-compiled mode to CLI11, which allows you to precompile @@ -7,7 +73,7 @@ the library, saving time on incremental rebuilds, making CLI11 more competitive on compile time with classic compiled CLI libraries. The header-only mode is still default, and is not yet distributed via binaries. -- Add `CLI11_PRECOMPILED` as an option. [#762][] +- Add `CLI11_PRECOMPILED` as an option [#762][] - Bugfix: Include `` in `FormatterFwd` [#727][] - Bugfix: Add missing `Macros.hpp` to `Error.hpp` [#755][] - Bugfix: Fix subcommand callback trigger [#733][] diff --git a/README.md b/README.md index bb75fd492..d1cedea35 100644 --- a/README.md +++ b/README.md @@ -206,8 +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 +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.
Note: If you don't like macros, this is what that macro expands to: (click to expand)

@@ -416,7 +416,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 @@ -452,7 +452,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 @@ -694,7 +694,7 @@ NOTES: If the container used in `IsMember`, `Transformer`, or fast search is performed first, and if that fails a linear search with the filters on the key values is performed. -- `CLI::FileOnDefaultPath(default_path)`: 🆕 can be used to check for files in a +- `CLI::FileOnDefaultPath(default_path)`: can be used to check for files in a default path. If used as a transform it will first check that a file exists, if it does nothing further is done, if it does not it tries to add a default Path to the file and search there again. If the file does not exist an error @@ -702,7 +702,7 @@ 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 +- `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 @@ -874,7 +874,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) @@ -886,7 +886,7 @@ 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 +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`. @@ -926,9 +926,9 @@ option_groups. These are: before matching. Validation is specified through `transform`, `check`, and `each` for an option. If an argument fails validation it is not an error and matching proceeds to the next available positional or extra arguments. -- `.validate_optional_arguments()`:🆕 Specify that optional arguments should - pass validation before being assigned to an option. Validation is specified - through `transform`, `check`, and `each` for an option. If an argument fails +- `.validate_optional_arguments()`: Specify that optional arguments should pass + validation before being assigned to an option. Validation is specified through + `transform`, `check`, and `each` for an option. If an argument fails validation it is not an error and matching proceeds to the next available positional subcommand or extra arguments. - `.excludes(option_or_subcommand)`: If given an option pointer or pointer to @@ -1014,9 +1014,9 @@ option_groups. These are: - `.prefix_command()`: Like `allow_extras`, but stop immediately on the first unrecognized item. 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 +- `.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 @@ -1223,8 +1223,8 @@ 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 🚧, +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: @@ -1297,9 +1297,9 @@ boolean values are not quoted. For options or flags which allow 0 arguments to be passed using an empty string in the config file, `{}`, or `[]` will convert the result to the default value -specified via `default_str` or `default_val` on the option 🆕. If no user -specified default is given the result is an empty string or the converted value -of an empty string. +specified via `default_str` or `default_val` on the option. If no user specified +default is given the result is an empty string or the converted value of an +empty string. NOTE: Transforms and checks can be used with the option pointer returned from set_config like any other option to validate the input if needed. It can also be @@ -1427,8 +1427,8 @@ CLI11 supports Unicode and wide strings as defined in the When using the command line on Windows with unicode arguments, your `main` function may already receive broken Unicode. Parsing `argv` at that point will -not give you a correct string. To fix this, you have three good options and two -bad ones: +not give you a correct string. To fix this, you have three options; the first is +recommended for cross-platform support: 1\. Replace `argv` with `app.ensure_utf8(argv)` before any arguments are parsed. `ensure_utf8` will do nothing on systems where `argv` is already in UTF-8 (Such @@ -1445,40 +1445,13 @@ int main(int argc, char** argv) { } ``` -2\. If you pass unmodified command-line arguments to CLI11, call `app.parse()` -instead of `app.parse(argc, argv)` (or `CLI11_PARSE(app)` instead of -`CLI11_PARSE(app, argc, argv)`). The library will find correct arguments by -itself. +Be sure you do not modify `argv` before this function call, as the correct +values will be reconstructed using Windows APIs and produced by this call. It +has no effect on other platforms and just passes through `argv`. -> [!NOTE] -> -> This approach may not work on weird OS configurations, such as when the -> `/proc` dir is missing on Linux systems (see also -> [#845](https://github.com/CLIUtils/CLI11/issues/845)). -> -> ```cpp -> int main() { -> CLI::App app; -> // ... -> CLI11_PARSE(app); -> } -> ``` - -3\. Get correct arguments with which the program was originally executed using -provided functions: `CLI::argc()` and `CLI::argv()`. These three methods are the -only cross-platform ways of handling unicode correctly. - -```cpp -int main() { - CLI::App app; - // ... - CLI11_PARSE(app, CLI::argc(), CLI::argv()); -} -``` - -

Bad options (click to expand)

+

Other options (click to expand)

-4\. Use the Windows-only non-standard `wmain` function, which accepts +2\. Use the Windows-only non-standard `wmain` function, which accepts `wchar_t *argv[]` instead of `char* argv[]`. Parsing this will allow CLI to convert wide strings to UTF-8 without losing information. @@ -1490,10 +1463,10 @@ int wmain(int argc, wchar_t *argv[]) { } ``` -5\. Retrieve arguments yourself by using Windows APIs like +3\. Retrieve arguments yourself by using Windows APIs like [`CommandLineToArgvW`](https://learn.microsoft.com/en-us/windows/win32/api/shellapi/nf-shellapi-commandlinetoargvw) and pass them to CLI. This is what the library is doing under the hood in -`CLI::argv()`. +`ensure_utf8`.