Streamline validators.md index

docs/validators/Alnum.md

@@ -14,12 +14,12 @@ Alphanumeric is a combination of alphabetic (a-z and A-Z) and numeric (0-9)
 characters.
 
 ```php
-v::alnum()->assert('foo 123');
-// → "foo 123" must contain only letters (a-z) and digits (0-9)
-
 v::alnum(' ')->assert('foo 123');
 // Validation passes successfully
 
+v::alnum()->assert('foo 123');
+// → "foo 123" must contain only letters (a-z) and digits (0-9)
+
 v::alnum()->assert('100%');
 // → "100%" must contain only letters (a-z) and digits (0-9)
 

docs/validators/Alpha.md

@@ -12,12 +12,12 @@ Validates whether the input contains only alphabetic characters. This is similar
 to [Alnum](Alnum.md), but it does not allow numbers.
 
 ```php
-v::alpha()->assert('some name');
-// → "some name" must contain only letters (a-z)
-
 v::alpha(' ')->assert('some name');
 // Validation passes successfully
 
+v::alpha()->assert('some name');
+// → "some name" must contain only letters (a-z)
+
 v::alpha()->assert('Cedric-Fabian');
 // → "Cedric-Fabian" must contain only letters (a-z)
 

docs/validators/AlwaysInvalid.md

@@ -10,6 +10,9 @@ SPDX-License-Identifier: MIT
 Validates any input as invalid.
 
 ```php
+v::not(v::alwaysInvalid())->assert('whatever');
+// Validation passes successfully
+
 v::alwaysInvalid()->assert('whatever');
 // → "whatever" must be valid
 ```

docs/validators/BetweenExclusive.md

@@ -10,12 +10,12 @@ SPDX-License-Identifier: MIT
 Validates whether the input is between two other values, exclusively.
 
 ```php
-v::betweenExclusive(10, 20)->assert(10);
-// → 10 must be greater than 10 and less than 20
-
 v::betweenExclusive('a', 'e')->assert('c');
 // Validation passes successfully
 
+v::betweenExclusive(10, 20)->assert(10);
+// → 10 must be greater than 10 and less than 20
+
 v::betweenExclusive(new DateTime('yesterday'), new DateTime('tomorrow'))->assert(new DateTime('today'));
 // Validation passes successfully
 

docs/validators/Call.md

@@ -9,6 +9,11 @@ SPDX-License-Identifier: MIT
 
 Validates the return of a [callable][] for a given input.
 
+```php
+v::call(str_split(...), v::arrayType()->lengthEquals(5))->assert('world');
+// Validation passes successfully
+```
+
 Consider the following variable:
 
 ```php

docs/validators/Callback.md

@@ -11,9 +11,7 @@ SPDX-License-Identifier: MIT
 Validates the input using the return of a given callable.
 
 ```php
-v::callback(
-    fn (int $input): bool => $input + ($input / 2) == 15,
-)->assert(10);
+v::callback(fn (int $input): bool => $input % 5 === 0,)->assert(10);
 // Validation passes successfully
 ```
 

docs/validators/Charset.md

@@ -11,12 +11,12 @@ SPDX-License-Identifier: MIT
 Validates if a string is in a specific charset.
 
 ```php
-v::charset('ASCII')->assert('açúcar');
-// → "açúcar" must only contain characters from the `["ASCII"]` charset
-
 v::charset('ASCII')->assert('sugar');
 // Validation passes successfully
 
+v::charset('ASCII')->assert('açúcar');
+// → "açúcar" must only contain characters from the `["ASCII"]` charset
+
 v::charset('ISO-8859-1', 'EUC-JP')->assert('日本国');
 // Validation passes successfully
 ```

docs/validators/Circuit.md

@@ -10,6 +10,11 @@ SPDX-License-Identifier: MIT
 
 Validates the input against a series of validators until the first fails.
 
+```php
+v::circuit(v::intVal(), v::floatVal())->assert(15);
+// Validation passes successfully
+```
+
 This validator can be handy for getting the least error messages possible from a chain.
 
 This validator can be helpful in combinations with [Lazy](Lazy.md). An excellent example is when you want to validate a

docs/validators/Cnpj.md

@@ -10,6 +10,11 @@ SPDX-License-Identifier: MIT
 Validates if the input is a Brazilian National Registry of Legal Entities (CNPJ) number.
 Ignores non-digit chars, so use `->digit()` if needed.
 
+```php
+v::cnpj()->assert('00394460005887');
+// Validation passes successfully
+```
+
 ## Templates
 
 ### `Cnpj::TEMPLATE_STANDARD`

docs/validators/Cpf.md

@@ -10,7 +10,7 @@ SPDX-License-Identifier: MIT
 Validates a Brazillian CPF number.
 
 ```php
-v::cpf()->assert('11598647644');
+v::cpf()->assert('95574461102');
 // Validation passes successfully
 ```
 

docs/validators/DateTimeDiff.md

@@ -15,15 +15,15 @@ The `$format` argument should follow PHP's [date()][] function. When the `$forma
 [Supported Date and Time Formats][] by PHP (see [strtotime()][]).
 
 ```php
+v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->assert('09/12/1990');
+// Validation passes successfully
+
 v::dateTimeDiff('years', v::equals(7))->assert('7 years ago');
 // → The number of years between now and "7 years ago" must be equal to 7
 
 v::dateTimeDiff('years', v::equals(7))->assert('7 years ago + 1 minute');
 // → The number of years between now and "7 years ago + 1 minute" must be equal to 7
 
-v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->assert('09/12/1990');
-// Validation passes successfully
-
 v::dateTimeDiff('years', v::greaterThan(18), 'd/m/Y')->assert('09/12/2023');
 // → The number of years between "01/01/2024" and "09/12/2023" must be greater than 18
 

docs/validators/Digit.md

@@ -11,12 +11,12 @@ SPDX-License-Identifier: MIT
 Validates whether the input contains only digits.
 
 ```php
-v::digit()->assert('020 612 1851');
-// → "020 612 1851" must contain only digits (0-9)
-
 v::digit(' ')->assert('020 612 1851');
 // Validation passes successfully
 
+v::digit()->assert('020 612 1851');
+// → "020 612 1851" must contain only digits (0-9)
+
 v::digit()->assert('172.655.537-21');
 // → "172.655.537-21" must contain only digits (0-9)
 

docs/validators/Executable.md

@@ -10,11 +10,11 @@ SPDX-License-Identifier: MIT
 Validates if a file is an executable.
 
 ```php
-v::executable()->assert('/path/to/file');
-// → "/path/to/file" must be an executable file
-
 v::executable()->assert('/path/to/executable');
 // Validation passes successfully
+
+v::executable()->assert('/path/to/file');
+// → "/path/to/file" must be an executable file
 ```
 
 ## Templates

docs/validators/GreaterThanOrEqual.md

@@ -10,12 +10,12 @@ SPDX-License-Identifier: MIT
 Validates whether the input is greater than or equal to a value.
 
 ```php
-v::intVal()->greaterThanOrEqual(10)->assert(9);
-// → 9 must be greater than or equal to 10
-
 v::intVal()->greaterThanOrEqual(10)->assert(10);
 // Validation passes successfully
 
+v::intVal()->greaterThanOrEqual(10)->assert(9);
+// → 9 must be greater than or equal to 10
+
 v::intVal()->greaterThanOrEqual(10)->assert(11);
 // Validation passes successfully
 ```

docs/validators/KeySet.md

@@ -11,6 +11,9 @@ SPDX-License-Identifier: MIT
 Validates a keys in a defined structure.
 
 ```php
+v::keySet(v::key('foo', v::intVal()))->assert(['foo' => 42]);
+// Validation passes successfully
+
 v::keySet(
     v::keyExists('foo'),
     v::keyExists('bar')
@@ -21,11 +24,6 @@ v::keySet(
 It will validate the keys in the array with the validators passed in the constructor.
 
 ```php
-v::keySet(
-    v::key('foo', v::intVal())
-)->assert(['foo' => 42]);
-// Validation passes successfully
-
 v::keySet(
     v::key('foo', v::intVal())
 )->assert(['foo' => 'string']);

docs/validators/Lazy.md

@@ -9,6 +9,11 @@ SPDX-License-Identifier: MIT
 
 Validates the input using a validator that is created from a callback.
 
+```php
+v::lazy(static fn($input) => v::boolVal())->assert(true);
+// Validation passes successfully
+```
+
 This validator is particularly useful when creating validators that rely on the input. A good example is validating whether a
 `confirmation` field matches the `password` field when processing data from a form.
 

docs/validators/Named.md

@@ -10,6 +10,9 @@ SPDX-License-Identifier: MIT
 Validates the input with the given validator, and uses the custom name in the error message.
 
 ```php
+v::named('Your email', v::email())->assert('foo@example.com');
+// Validation passes successfully
+
 v::named('Your email', v::email())->assert('not an email');
 // → Your email must be a valid email address
 ```

docs/validators/NfeAccessKey.md

@@ -10,6 +10,9 @@ SPDX-License-Identifier: MIT
 Validates the access key of the Brazilian electronic invoice (NFe).
 
 ```php
+v::nfeAccessKey()->assert('52060433009911002506550120000007800267301615');
+// Validation passes successfully
+
 v::nfeAccessKey()->assert('31841136830118868211870485416765268625116906');
 // → "31841136830118868211870485416765268625116906" must be a valid NFe access key
 ```

docs/validators/Odd.md

@@ -10,11 +10,11 @@ SPDX-License-Identifier: MIT
 Validates whether the input is an odd number or not.
 
 ```php
-v::odd()->assert(0);
-// → 0 must be an odd number
-
 v::odd()->assert(3);
 // Validation passes successfully
+
+v::odd()->assert(0);
+// → 0 must be an odd number
 ```
 
 Using `intVal()` before `odd()` is a best practice.

docs/validators/ScalarVal.md

@@ -10,11 +10,11 @@ SPDX-License-Identifier: MIT
 Validates whether the input is a scalar value or not.
 
 ```php
-v::scalarVal()->assert([]);
-// → `[]` must be a scalar value
-
 v::scalarVal()->assert(135.0);
 // Validation passes successfully
+
+v::scalarVal()->assert([]);
+// → `[]` must be a scalar value
 ```
 
 ## Templates

docs/validators/Templated.md

@@ -11,8 +11,11 @@ SPDX-License-Identifier: MIT
 Defines a validator with a custom message template.
 
 ```php
-v::templated('You must provide a valid email to signup', v::email())->assert('not an email');
-// → You must provide a valid email to signup
+v::templated('You must provide a valid email', v::email())->assert('foo@bar.com');
+// Validation passes successfully
+
+v::templated('You must provide a valid email', v::email())->assert('not an email');
+// → You must provide a valid email
 
 v::templated(
     'The author of the page {{title}} is empty, please fill it up.',

docs/validators/Uploaded.md

@@ -9,11 +9,6 @@ SPDX-License-Identifier: MIT
 
 Validates if the given data is a file that was uploaded via HTTP POST.
 
-```php
-v::uploaded()->assert('/path/of/an/uploaded/file');
-// → "/path/of/an/uploaded/file" must be an uploaded file
-```
-
 ## Templates
 
 ### `Uploaded::TEMPLATE_STANDARD`

docs/validators/Uuid.md

@@ -12,12 +12,12 @@ Validates whether the input is a valid UUID. It also supports validation of
 specific versions 1 to 8.
 
 ```php
-v::uuid()->assert('Hello World!');
-// → "Hello World!" must be a valid UUID
-
 v::uuid()->assert('eb3115e5-bd16-4939-ab12-2b95745a30f3');
 // Validation passes successfully
 
+v::uuid()->assert('Hello World!');
+// → "Hello World!" must be a valid UUID
+
 v::uuid()->assert('eb3115e5bd164939ab122b95745a30f3');
 // Validation passes successfully
 

src-dev/Markdown/Content.php

@@ -25,6 +25,7 @@
 use function implode;
 use function max;
 use function preg_match;
+use function preg_replace;
 use function reset;
 use function rtrim;
 use function sprintf;
@@ -111,6 +112,14 @@ public function anchorListItem(string $title, string $href): void
         $this->listItem(sprintf('[%s](%s)', $title, $href));
     }
 
+    public function reference(string $title, string $href, string|null $description = null): void
+    {
+        $this->lines[] = match ($description) {
+            null => sprintf('[%s]: %s', $title, $href),
+            default => sprintf('[%s]: %s "%s"', $title, $href, $description),
+        };
+    }
+
     public function extractSpdx(): self
     {
         $start = 0;
@@ -130,6 +139,11 @@ public function extractSpdx(): self
         return new self(array_slice($this->lines, $start, $end + 2));
     }
 
+    public static function stripRefs(string $text): string
+    {
+        return preg_replace('/\[(.+?)\](?:\[\]|\(.+?\))/', '$1', $text) ?? $text;
+    }
+
     public function withSection(Content $content): self
     {
         $firstLine = reset($content->lines);