Squashed 'libs/CommService/' content from commit 7ccc0fc

git-subtree-dir: libs/CommService
git-subtree-split: 7ccc0fce88bbc5969df060058cf0fb57abe3bcf9

libs/CLI11/book/chapters/validators.md

@@ -0,0 +1,66 @@
+# 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              |