67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# Validators
|
|
|
|
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.
|
|
|
|
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
|
|
constructor also.
|
|
|
|
An example of a custom validator:
|
|
|
|
```cpp
|
|
struct LowerCaseValidator : public Validator {
|
|
LowerCaseValidator() {
|
|
name_ = "LOWER";
|
|
func_ = [](const std::string &str) {
|
|
if(CLI::detail::to_lower(str) != str)
|
|
return std::string("String is not lower case");
|
|
else
|
|
return std::string();
|
|
};
|
|
}
|
|
};
|
|
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`.
|
|
|
|
The built-in validators for CLI11 are:
|
|
|
|
| Validator | Description |
|
|
| ------------------- | ---------------------------------------------------------------------- |
|
|
| `ExistingFile` | Check for existing file (returns error message if check fails) |
|
|
| `ExistingDirectory` | Check for an existing directory (returns error message if check fails) |
|
|
| `ExistingPath` | Check for an existing path |
|
|
| `NonexistentPath` | Check for an non-existing path |
|
|
| `Range(min=0, max)` | Produce a range (factory). Min and max are inclusive. |
|
|
|
|
And, the protected members that you can set when you make your own are:
|
|
|
|
| Type | Member | Description |
|
|
| ------------------------------------------- | -------------------- | ---------------------------------------------------------------------- |
|
|
| `std::function<std::string(std::string &)>` | `func_` | Core validation function - modifies input and returns "" if successful |
|
|
| `std::function<std::string()>` | `desc_function` | Optional description function (uses `description_` instead if not set) |
|
|
| `std::string` | `name_` | The name for search purposes |
|
|
| `int` (`-1`) | `application_index_` | The element this validator applies to (-1 for all) |
|
|
| `bool` (`true`) | `active_` | This can be disabled |
|
|
| `bool` (`false`) | `non_modifying_` | Specify that this is a Validator instead of a Transformer |
|