From b7b02c1d2f57c9c84906d740e0637c19c6086dca Mon Sep 17 00:00:00 2001 From: JonathanGzzBen Date: Sun, 12 Dec 2021 15:09:41 -0600 Subject: [PATCH 1/2] Update transform validators documentation Adds an example on how to use transform validator objects and clarifies the usage of the return type of the base function. --- book/chapters/validators.md | 41 ++++++++++++++++++++++++++----------- 1 file changed, 29 insertions(+), 12 deletions(-) diff --git a/book/chapters/validators.md b/book/chapters/validators.md index 06e42c80a..6bda44528 100644 --- a/book/chapters/validators.md +++ b/book/chapters/validators.md @@ -5,20 +5,36 @@ There are two forms of validators: * `transform` validators: mutating * `check` validators: non-mutating (recommended unless the parsed string must be mutated) -A transform validator comes in one form, a function with the signature `std::string(std::string)`. -The function will take a string and return the modified version of the string. If there is an error, -the function should throw a `CLI::ValidationError` with the appropriate reason as a message. +A transform validator comes in one form, a function with the signature `std::string(std::string&)`. The function will +take a string and return an error message, or an empty string if input is valid. If there is an error, the function +should throw a `CLI::ValidationError` with the appropriate reason as a message. -However, `check` validators come in two forms; either a simple function with the const version of the -above signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This -structure has two members that a user should set; one (`func_`) is the function to add to the Option +An example of a mutating validator: + +```cpp +auto transform_validator = CLI::Validator( + [](std::string &input) { + if (input == "error") { + return "error is not a valid value"; + } else if (input == "unexpected") { + throw CLI::ValidationError{"Unexpected error"}; + } + input = "new string"; + return ""; + }, "VALIDATOR DESCRIPTION", "Validator name"); + +cli_global.add_option("option")->transform(transform_validator); +``` + +However, `check` validators come in two forms; either a simple function with the const version of the above +signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This structure has two members +that a user should set; one (`func_`) is the function to add to the Option (exactly matching the above function signature, since it will become that function), and the other is -`name_`, and is the type name to set on the Option (unless empty, in which case the typename will be -left unchanged). +`name_`, and is the type name to set on the Option (unless empty, in which case the typename will be left unchanged). -Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them -as if they were a function. In CLI11, const static versions of the validators are provided so that -the user does not have to call a constructor also. +Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them as if they were a +function. In CLI11, const static versions of the validators are provided so that the user does not have to call a +constructor also. An example of a custom validator: @@ -37,7 +53,8 @@ struct LowerCaseValidator : public Validator { const static LowerCaseValidator Lowercase; ``` -If you were not interested in the extra features of Validator, you could simply pass the lambda function above to the `->check()` method of `Option`. +If you were not interested in the extra features of Validator, you could simply pass the lambda function above to +the `->check()` method of `Option`. The built-in validators for CLI11 are: From 2dc19a76f6fc80aec4de6011874df8229bafa8cd Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sat, 15 Jun 2024 00:51:00 +0000 Subject: [PATCH 2/2] style: pre-commit.ci fixes --- book/chapters/validators.md | 25 +++++++++++++++---------- 1 file changed, 15 insertions(+), 10 deletions(-) diff --git a/book/chapters/validators.md b/book/chapters/validators.md index ae9f54654..f4f03c7c2 100644 --- a/book/chapters/validators.md +++ b/book/chapters/validators.md @@ -6,9 +6,11 @@ There are two forms of validators: - `check` validators: non-mutating (recommended unless the parsed string must be mutated) -A transform validator comes in one form, a function with the signature `std::string(std::string&)`. The function will -take a string and return an error message, or an empty string if input is valid. If there is an error, the function -should throw a `CLI::ValidationError` with the appropriate reason as a message. +A transform validator comes in one form, a function with the signature +`std::string(std::string&)`. The function will take a string and return an error +message, or an empty string if input is valid. If there is an error, the +function should throw a `CLI::ValidationError` with the appropriate reason as a +message. An example of a mutating validator: @@ -27,14 +29,17 @@ auto transform_validator = CLI::Validator( cli_global.add_option("option")->transform(transform_validator); ``` -However, `check` validators come in two forms; either a simple function with the const version of the above -signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This structure has two members -that a user should set; one (`func_`) is the function to add to the Option -(exactly matching the above function signature, since it will become that function), and the other is -`name_`, and is the type name to set on the Option (unless empty, in which case the typename will be left unchanged). +However, `check` validators come in two forms; either a simple function with the +const version of the above signature, `std::string(const std::string &)`, or a +subclass of `struct CLI::Validator`. This structure has two members that a user +should set; one (`func_`) is the function to add to the Option (exactly matching +the above function signature, since it will become that function), and the other +is `name_`, and is the type name to set on the Option (unless empty, in which +case the typename will be left unchanged). -Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them as if they were a -function. In CLI11, const static versions of the validators are provided so that the user does not have to call a +Validators can be combined with `&` and `|`, and they have an `operator()` so +that you can call them as if they were a function. In CLI11, const static +versions of the validators are provided so that the user does not have to call a constructor also. An example of a custom validator: