Add v::format() to check if data is already in a specific format

This validator is not so much about how we present the input
during error messages, but in what format data already is formatted.

Author: alganet

aliases.php

@@ -13,7 +13,12 @@
 declare(strict_types=1);
 
 use Respect\Validation\ValidatorBuilder;
+use Respect\StringFormatter\FormatterBuilder;
 
 if (!class_exists('v')) {
     class_alias(ValidatorBuilder::class, 'v');
 }
+
+if (!class_exists('f')) {
+    class_alias(FormatterBuilder::class, 'f');
+}

docs/validators.md

@@ -27,7 +27,7 @@ In this page you will find a list of validators by their category.
 
 **Date and Time**: [Date][] - [DateTime][] - [DateTimeDiff][] - [LeapDate][] - [LeapYear][] - [Time][]
 
-**Display**: [Masked][] - [Named][] - [Templated][]
+**Display**: [Format][] - [Masked][] - [Named][] - [Templated][]
 
 **File system**: [Directory][] - [Executable][] - [Exists][] - [Extension][] - [File][] - [Image][] - [Mimetype][] - [Readable][] - [Size][] - [SymbolicLink][] - [Writable][]
 
@@ -49,7 +49,7 @@ In this page you will find a list of validators by their category.
 
 **Objects**: [Attributes][] - [Instance][] - [ObjectType][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
-**Strings**: [Alnum][] - [Alpha][] - [Base64][] - [Charset][] - [Consonant][] - [Contains][] - [ContainsAny][] - [ContainsCount][] - [Control][] - [Digit][] - [Emoji][] - [EndsWith][] - [Graph][] - [HexRgbColor][] - [In][] - [Json][] - [Lowercase][] - [Phone][] - [PostalCode][] - [Printable][] - [Punct][] - [Regex][] - [Slug][] - [Sorted][] - [Space][] - [Spaced][] - [StartsWith][] - [StringType][] - [StringVal][] - [Uppercase][] - [Uuid][] - [Version][] - [Vowel][] - [Xdigit][]
+**Strings**: [Alnum][] - [Alpha][] - [Base64][] - [Charset][] - [Consonant][] - [Contains][] - [ContainsAny][] - [ContainsCount][] - [Control][] - [Digit][] - [Emoji][] - [EndsWith][] - [Format][] - [Graph][] - [HexRgbColor][] - [In][] - [Json][] - [Lowercase][] - [Phone][] - [PostalCode][] - [Printable][] - [Punct][] - [Regex][] - [Slug][] - [Sorted][] - [Space][] - [Spaced][] - [StartsWith][] - [StringType][] - [StringVal][] - [Uppercase][] - [Uuid][] - [Version][] - [Vowel][] - [Xdigit][]
 
 **Structures**: [Attributes][] - [Key][] - [KeyExists][] - [KeyOptional][] - [KeySet][] - [Property][] - [PropertyExists][] - [PropertyOptional][]
 
@@ -118,6 +118,7 @@ In this page you will find a list of validators by their category.
 - [Finite][] - `v::finite()->assert('10');`
 - [FloatType][] - `v::floatType()->assert(1.5);`
 - [FloatVal][] - `v::floatVal()->assert(1.5);`
+- [Format][] - `v::format(f::pattern('00-00'))->assert('42-33');`
 - [Graph][] - `v::graph()->assert('LKM@#$%4;');`
 - [GreaterThan][] - `v::greaterThan(10)->assert(11);`
 - [GreaterThanOrEqual][] - `v::intVal()->greaterThanOrEqual(10)->assert(10);`
@@ -274,6 +275,7 @@ In this page you will find a list of validators by their category.
 [Finite]: validators/Finite.md "Validates if the input is a finite number."
 [FloatType]: validators/FloatType.md "Validates whether the type of the input is float."
 [FloatVal]: validators/FloatVal.md "Validate whether the input value is float."
+[Format]: validators/Format.md "Validates whether an input is already formatted as the result of applying a provided"
 [Graph]: validators/Graph.md "Validates if all characters in the input are printable and actually creates"
 [GreaterThan]: validators/GreaterThan.md "Validates whether the input is greater than a value."
 [GreaterThanOrEqual]: validators/GreaterThanOrEqual.md "Validates whether the input is greater than or equal to a value."

docs/validators/Format.md

@@ -0,0 +1,68 @@
+<!--
+SPDX-License-Identifier: MIT
+SPDX-FileCopyrightText: (c) Respect Project Contributors
+SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+-->
+
+# Format
+
+- `Format(Formatter $formatter)`
+
+Validates whether an input is already formatted as the result of applying a provided
+[Respect\StringFormatter][] `Formatter` to it. You can build formatters using
+`Respect\StringFormatter\FormatterBuilder` (commonly aliased as `f`).
+
+```php
+v::format(f::pattern('00-00'))->assert('42-33');
+// Validation passes successfully
+
+v::format(f::pattern('00-00'))->assert('42.33');
+// → "42.33" must be formatted as "42-33"
+
+v::format(f::mask('1-@'))->assert('alganet@gmail.com');
+// → "alganet@gmail.com" must be formatted as "*******@gmail.com"
+
+v::not(v::format(f::pattern('00-00')))->assert('42-33');
+// → "42-33" must not be formatted as "42-33"
+
+v::named('Vanity plate', v::format(f::pattern('AAA-0000')))->assert('DAD8008');
+// → Vanity plate must be formatted as "DAD-8008"
+```
+
+This validator is useful when you need to assert that data is already in a desired
+presentation (for example, ensuring that a masking tool was already applied or that
+stored data follows a required display format).
+
+## Templates
+
+### `Format::TEMPLATE_STANDARD`
+
+|       Mode | Template                                           |
+| ---------: | :------------------------------------------------- |
+|  `default` | {{subject}} must be formatted as {{formatted}}     |
+| `inverted` | {{subject}} must not be formatted as {{formatted}} |
+
+## Template placeholders
+
+| Placeholder | Description                                                      |
+| ----------- | ---------------------------------------------------------------- |
+| `formatted` | The value resulting from applying the provided formatter to the input |
+| `subject`   | The validated input or the custom validator name (if specified).     |
+
+## Categorization
+
+- Display
+- Strings
+
+## Changelog
+
+| Version | Description |
+| ------: | :---------- |
+|   3.0.0 | Created     |
+
+## See Also
+
+- [Masked](Masked.md)
+- [Templated](Templated.md)
+
+[Respect\StringFormatter]: https://github.com/Respect/StringFormatter