Compile the pattern for PatternFormatter

The verification that was made upon the pattern was almost like
a parser/tokenizer in itself.

This change leverages that behavior to introduce full pattern
compilation.

When the PatternFormatter encounters a novel pattern that it
has never seen before, it compiles that pattern into a 3-step
CompiledPattern instance that has a search regex, a replacement
pattern and instructions for the callback.

Upon seeing already compiled patterns, all the PatternFormatter
has to do is perform the motions (one preg_replace_callback)
of the existing compiled pattern.

Further steps for pattern canonicalization could be taken, such
as normalizing equivalent patterns into a single form, so they
could share the same cached space. However, that micro-optimization
was too expensive and counter-productive.

This change also opens up possibilities for in-file warmup, as
CompiledPattern instances are simple objects. An user could
pre-compile his/her hot-path patterns beforehand to share the
cache even across diferent processes.

Author: alganet

src/Internal/CompiledPattern.php

@@ -0,0 +1,191 @@
+<?php
+
+/*
+ * SPDX-FileCopyrightText: (c) Respect Project Contributors
+ * SPDX-License-Identifier: ISC
+ * SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
+ */
+
+declare(strict_types=1);
+
+namespace Respect\StringFormatter\Internal;
+
+use Respect\StringFormatter\InvalidFormatterException;
+
+use function array_keys;
+use function count;
+use function implode;
+use function mb_strtolower;
+use function mb_strtoupper;
+use function mb_substr;
+use function preg_match;
+use function preg_match_all;
+use function sprintf;
+use function str_starts_with;
+use function strtolower;
+use function substr;
+
+use const PREG_OFFSET_CAPTURE;
+
+final class CompiledPattern
+{
+    private const array FILTERS = [
+        '#' => '.',
+        '0' => '[[:digit:]]',
+        'A' => '[[:upper:]]',
+        'a' => '[[:lower:]]',
+        'C' => '[[:alpha:]]',
+        'W' => '[[:alnum:]]',
+    ];
+
+    private const array TRANSFORM_MAP = ['l' => 'lower', 'u' => 'upper', 'i' => 'invert'];
+
+    /** @var array<string, CompiledPattern> */
+    private static array $compiledPatterns = [];
+
+    /** @var array<string, array<int, string>> */
+    private static array $compiledQualifiers = [];
+
+    private function __construct(
+        private(set) readonly string $pattern,
+        private(set) readonly string $search,
+        private(set) readonly string $replacement,
+        /** @var array<int, array{filter: string, transform: string|null}> */
+        private(set) readonly array $instructions,
+    ) {
+    }
+
+    public static function compile(string $pattern): self
+    {
+        if (isset(self::$compiledPatterns[$pattern])) {
+            return self::$compiledPatterns[$pattern];
+        }
+
+        if ($pattern === '') {
+            throw new InvalidFormatterException('Pattern cannot be empty');
+        }
+
+        $search = '';
+        $replacement = '';
+        $instructions = [];
+        $groupIndex = 1;
+
+        $transformState = null;
+        $nextTransform = null;
+
+        preg_match_all(sprintf(
+            '/(?:\\\\.|[%1$s]|(?:\{[^}]*\}|[*+?])|[^\\\%1$s{}+*?]+|.)/u',
+            implode('', array_keys(self::FILTERS)),
+        ), $pattern, $tokens, PREG_OFFSET_CAPTURE);
+
+        $tokenList = $tokens[0];
+        $count = count($tokenList);
+
+        for ($i = 0; $i < $count; $i++) {
+            [$tokenText, $offset] = $tokenList[$i];
+
+            if (str_starts_with($tokenText, '\\')) {
+                if ($tokenText === '\\') {
+                    throw new InvalidFormatterException('Incomplete escape sequence at end of pattern');
+                }
+
+                $char = mb_substr($tokenText, 1);
+
+                if ($char === 'd') {
+                    $inner = '.';
+                    $search .= "((?:.*?$inner){0,1})";
+                    $replacement .= "%{$groupIndex}$";
+                    $instructions[$groupIndex] = ['filter' => "/$inner/u", 'transform' => 'delete'];
+                    $groupIndex++;
+                    continue;
+                }
+
+                if ($char === 'E') {
+                    $transformState = null;
+                    continue;
+                }
+
+                if (isset(self::TRANSFORM_MAP[$char])) {
+                    $nextTransform = self::TRANSFORM_MAP[$char];
+                    continue;
+                }
+
+                $lowerChar = strtolower($char);
+                if (isset(self::TRANSFORM_MAP[$lowerChar]) && $char !== $lowerChar) {
+                    $transformState = self::TRANSFORM_MAP[$lowerChar];
+                    continue;
+                }
+
+                $replacement .= $char;
+                continue;
+            }
+
+            if (isset(self::FILTERS[$tokenText])) {
+                $filterChar = $tokenText;
+                $regexQuantifier = '{0,1}';
+
+                if (isset($tokenList[$i + 1]) && preg_match('/^(?:\{[^}]*\}|[*+?])$/u', $tokenList[$i + 1][0])) {
+                    $i++;
+                    $regexQuantifier = self::compileQualifier($tokenList[$i][0], $tokenList[$i][1]);
+                }
+
+                $inner = self::FILTERS[$filterChar];
+                $search .= "((?:.*?$inner)$regexQuantifier)";
+
+                $replacement .= "%{$groupIndex}$";
+                $instructions[$groupIndex] = [
+                    'filter' => "/$inner/u",
+                    'transform' => $nextTransform ?? $transformState,
+                ];
+
+                $groupIndex++;
+                $nextTransform = null;
+                continue;
+            }
+
+            if (preg_match('/^(?:\{[^}]*\}|[*+?])$/u', $tokenText)) {
+                throw new InvalidFormatterException(sprintf('Quantifier "%s" must follow a filter pattern at position %d', $tokenText[0], $offset));
+            }
+
+            if (str_starts_with($tokenText, '{')) {
+                 throw new InvalidFormatterException(sprintf('Invalid or malformed quantifier at position %d', $offset));
+            }
+
+            $replacement .= $tokenText;
+        }
+
+        return self::$compiledPatterns[$pattern] = new self($pattern, '/^' . $search . '/us', $replacement, $instructions);
+    }
+
+    public static function transform(string $val, string|null $transform): string
+    {
+        return match ($transform) {
+            'delete' => '',
+            'lower' => mb_strtolower($val),
+            'upper' => mb_strtoupper($val),
+            'invert' => mb_strtolower($val) ^ mb_strtoupper($val) ^ $val,
+            default => $val,
+        };
+    }
+
+    private static function compileQualifier(string $token, int $offset): string
+    {
+        if (isset(self::$compiledQualifiers[$token][$offset])) {
+            return self::$compiledQualifiers[$token][$offset];
+        }
+
+        if ($token === '*' || $token === '+') {
+            return '*';
+        }
+
+        $content = substr($token, 1, -1);
+        if ($content === '' || $content === ',' || !preg_match('/^(\d+(?:,\d*)?|,\d+)$/', $content)) {
+            throw new InvalidFormatterException(sprintf('Invalid or malformed quantifier at position %d', $offset));
+        }
+
+        preg_match('/^\{(\d*)(?:,(\d*))?\}$/', $token, $m);
+        $max = $m[2] ?? $m[1];
+
+        return self::$compiledQualifiers[$token][$offset] = $max === '' ? '*' : "{0,$max}";
+    }
+}