Streamline validators.md index

Makes it so the index looks more like a cheatsheet, condensing
information instead of making long lists that require lots of
scrolling to explore.

Additionally, the happy path for each validator was also
added, providing a quick reference use for comparison.

The direct markdown links were replaced by titled markdown
references, offering mouse-over tooltips over links that
display the validator one-line description.

Author: alganet

docs/validators.md

@@ -11,10 +11,8 @@ 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);
-// Validation passes successfully
+v::callback(fn (int $input): bool => $input % 5,)->assert(10);
+// → 10 must be valid
 ```
 
 ## Templates

docs/validators/Callback.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/Circuit.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::cpf()->assert('00394460005887');
+// → "00394460005887" must be a valid CPF number
+```
+
 ## Templates
 
 ### `Cnpj::TEMPLATE_STANDARD`

docs/validators/Cnpj.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/GreaterThanOrEqual.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/Odd.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
 

docs/validators/Uuid.md

@@ -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);

src-dev/Markdown/Content.php

@@ -17,7 +17,9 @@
 
 use function array_keys;
 use function dirname;
+use function implode;
 use function ksort;
+use function preg_match;
 use function sort;
 use function sprintf;
 use function str_ends_with;
@@ -38,15 +40,19 @@ public function lint(File $file): File
         $validators = $this->getSortedListOfValidators();
 
         $validatorsByCategory = [];
+        $validatorsDescriptions = [];
+        $validatorsExamples = [];
         foreach ($validators as $validator) {
-            foreach ($this->getCategoriesByValidator($validator) as $category) {
+            $validatorInfo = $this->getValidatorInfo($validator);
+            foreach ($validatorInfo['categories'] as $category) {
                 $validatorsByCategory[$category] ??= [];
                 $validatorsByCategory[$category][] = $validator;
+                $validatorsDescriptions[$validator] = $validatorInfo['description'];
+                $validatorsExamples[$validator] = $validatorInfo['example'];
             }
         }
 
         ksort($validatorsByCategory);
-        $validatorsByCategory['Alphabetically'] = $validators;
 
         $categories = array_keys($validatorsByCategory);
 
@@ -55,16 +61,33 @@ public function lint(File $file): File
         $content->emptyLine();
 
         foreach ($categories as $category) {
-            $content->h2($category);
             $categoryValidators = $validatorsByCategory[$category];
             sort($categoryValidators);
+            $refs = [];
             foreach ($categoryValidators as $categoryValidator) {
-                $content->anchorListItem($categoryValidator, sprintf('validators/%s.md', $categoryValidator));
+                $refs[] = sprintf('[%s][]', $categoryValidator);
             }
 
+            $content->paragraph(sprintf('**%s**: %s', $category, implode(' - ', $refs)));
+
             $content->emptyLine();
         }
 
+        $content->h2('Alphabetically');
+        foreach ($validators as $validator) {
+            $content->listItem(sprintf('[%s][] - `%s`', $validator, $validatorsExamples[$validator]));
+        }
+
+        $content->emptyLine();
+
+        foreach (array_keys($validatorsDescriptions) as $validator) {
+            $content->reference(
+                $validator,
+                sprintf('validators/%s.md', $validator),
+                $validatorsDescriptions[$validator],
+            );
+        }
+
         return $file->withContent($content);
     }
 
@@ -88,10 +111,22 @@ private function getSortedListOfValidators(): array
     }
 
     /** @return array<string> */
-    private function getCategoriesByValidator(string $validator): array
+    private function getValidatorInfo(string $validator): array
     {
         $content = Content::from(sprintf('%s/validators/%s.md', dirname(__DIR__, 2) . '/../docs', $validator));
         $section = $content->getSection('## Categorization');
+        $description = '';
+        $example = '';
+        foreach ($content->getSection(sprintf('# %s', $validator)) as $line) {
+            if ($description === '' && preg_match('/^[A-Z]/', $line) === 1) {
+                $description = $line;
+            }
+
+            if (preg_match('/^v::/', $line) === 1) {
+                $example = $line;
+                break;
+            }
+        }
 
         $categories = [];
         foreach ($section as $line) {
@@ -102,6 +137,10 @@ private function getCategoriesByValidator(string $validator): array
             $categories[] = trim(substr($line, 1));
         }
 
-        return $categories;
+        return [
+            'categories' => $categories,
+            'description' => Content::stripRefs($description),
+            'example' => $example,
+        ];
     }
 }