Move and refactor more Convert methods

lkrms · lkrms · commit f2bf03d91e13 · 2024-02-07T20:48:56.000+11:00
- Move `Convert::toInt()` to `Get::integer()`
- Fix issue where `Get::value()` may inadvertently call an arbitrary
  function by only calling `Closure` instances
- Add `Str::matchCase()`
- In `Inflect::format()`:
  - Allow arbitrary placement of whitespace and hyphens in words
  - Allow words to be empty
  - Add `#` as a recognised word
  - Match the case of the placeholder
- Add `Inflect::formatRange()`
- Remove `Convert::pluralRange()` in favour of `Inflect::formatRange()`
diff --git a/src/Utility/Convert.php b/src/Utility/Convert.php
@@ -20,19 +20,6 @@
  */
 final class Convert extends Utility
 {
-    /**
-     * Convert a value to an integer, preserving null
-     *
-     * @param mixed $value
-     */
-    public static function toInt($value): ?int
-    {
-        if ($value === null) {
-            return null;
-        }
-        return (int) $value;
-    }
-
     /**
      * Expand tabs to spaces
      */
@@ -123,24 +110,6 @@ public static function ellipsize(string $value, int $length): string
         return $value;
     }
 
-    /**
-     * Get a phrase like "between lines 3 and 11" or "on platform 23"
-     *
-     * @param string|null $plural `"{$singular}s"` is used if `$plural` is
-     * `null`.
-     */
-    public static function pluralRange(
-        int $from,
-        int $to,
-        string $singular,
-        ?string $plural = null,
-        string $preposition = 'on'
-    ): string {
-        return $to - $from
-            ? sprintf('between %s %d and %d', $plural === null ? $singular . 's' : $plural, $from, $to)
-            : sprintf('%s %s %d', $preposition, $singular, $from);
-    }
-
     /**
      * Convert a list of "key=value" strings to an array like ["key" => "value"]
      *
diff --git a/src/Utility/Get.php b/src/Utility/Get.php
@@ -10,6 +10,7 @@
 use Lkrms\Support\Catalog\RegularExpression as Regex;
 use Lkrms\Utility\Catalog\CopyFlag;
 use Psr\Container\ContainerInterface as PsrContainerInterface;
+use Closure;
 use DateTimeInterface;
 use DateTimeZone;
 use ReflectionClass;
@@ -47,6 +48,21 @@ public static function boolean($value): ?bool
         return (bool) $value;
     }
 
+    /**
+     * Cast a value to integer, preserving null
+     *
+     * @param mixed $value
+     * @return ($value is null ? null : int)
+     */
+    public static function integer($value): ?int
+    {
+        if ($value === null) {
+            return null;
+        }
+
+        return (int) $value;
+    }
+
     /**
      * Convert a scalar to the type it appears to be
      *
@@ -65,13 +81,14 @@ public static function apparent($value, bool $toFloat = true, bool $toBool = tru
         if (!is_string($value)) {
             throw new InvalidArgumentTypeException(1, 'value', 'int|float|string|bool|null', $value);
         }
-        if (Str::lower(trim($value)) === 'null') {
+        $trimmed = trim($value);
+        if (Str::lower($trimmed) === 'null') {
             return null;
         }
         if (Pcre::match('/^' . Regex::INTEGER_STRING . '$/', $value)) {
             return (int) $value;
         }
-        if ($toFloat && is_numeric($value)) {
+        if ($toFloat && is_numeric($trimmed)) {
             return (float) $value;
         }
         if ($toBool && Pcre::match(
@@ -86,17 +103,17 @@ public static function apparent($value, bool $toFloat = true, bool $toBool = tru
     }
 
     /**
-     * Resolve a callable to its return value
+     * Resolve a closure to its return value
      *
      * @template T
      *
-     * @param (callable(mixed...): T)|T $value
-     * @param mixed ...$args Passed to `$value` if it is callable.
+     * @param (Closure(mixed...): T)|T $value
+     * @param mixed ...$args Passed to `$value` if it is a closure.
      * @return T
      */
     public static function value($value, ...$args)
     {
-        if (is_callable($value)) {
+        if ($value instanceof Closure) {
             return $value(...$args);
         }
         return $value;
diff --git a/src/Utility/Inflect.php b/src/Utility/Inflect.php
@@ -3,12 +3,83 @@
 namespace Lkrms\Utility;
 
 use Lkrms\Concept\Utility;
+use Lkrms\Exception\InvalidArgumentException;
+use Closure;
 
 /**
  * Inflect English words
  */
-class Inflect extends Utility
+final class Inflect extends Utility
 {
+    /**
+     * Inflect placeholders in a string in the singular if a range covers 1
+     * value, or in the plural otherwise
+     *
+     * For example:
+     *
+     * ```php
+     * <?php
+     * $message = Inflect::formatRange('{{#:on:from}} {{#:line}} {{#}}', $from, $to);
+     * ```
+     *
+     * The word used between `$from` and `$to` (default: `to`) can be given
+     * explicitly using the following syntax:
+     *
+     * ```php
+     * <?php
+     * $message = Inflect::formatRange('{{#:at:between}} {{#:value}} {{#:#:and}}', $from, $to);
+     * ```
+     *
+     * @see Inflect::format()
+     *
+     * @param int|float $from
+     * @param int|float $to
+     * @param mixed ...$values Passed to {@see sprintf()} with the inflected
+     * string if given.
+     */
+    public static function formatRange(string $format, $from, $to, ...$values): string
+    {
+        if (is_float($from) xor is_float($to)) {
+            throw new InvalidArgumentException('$from and $to must be of the same type');
+        }
+
+        $singular = $from === $to;
+        $zero = $singular && $from === 0;
+        $one = $singular && $from === 1;
+        $count = $singular ? ($zero ? 0 : 1) : 2;
+
+        $callback = $singular
+            ? fn(): string =>
+                (string) $from
+            : fn(?string $pluralWord): string =>
+                sprintf('%s %s %s', $from, $pluralWord ?? 'to', $to);
+
+        if ($zero) {
+            $no = 'no';
+        }
+
+        $replace = [
+            '#' => $callback,
+            '' => $callback,
+        ];
+
+        if ($zero || $one) {
+            $replace += [
+                'no' => $no ?? $callback,
+                'a' => $no ?? 'a',
+                'an' => $no ?? 'an',
+            ];
+        } else {
+            $replace += [
+                'no' => $callback,
+                'a' => $callback,
+                'an' => $callback,
+            ];
+        }
+
+        return self::doFormat($format, $count, $replace, false, ...$values);
+    }
+
     /**
      * Inflect placeholders in a string in the singular if a count is 1, or in
      * the plural otherwise
@@ -20,8 +91,9 @@ class Inflect extends Utility
      * $message = Inflect::format('{{#}} {{#:entry}} {{#:was}} processed', $count);
      * ```
      *
-     * The following verbs are recognised:
+     * The following words are recognised:
      *
+     * - `#` (unconditionally replaced with a number)
      * - `no` (replaced with a number if `$count` is not `0`)
      * - `a`, `an` (replaced with a number if `$count` is plural, `no` if
      *   `$count` is `0`)
@@ -40,30 +112,31 @@ class Inflect extends Utility
      * '{{#:matrix:matrices}}';
      * ```
      *
-     * @param mixed ...$values Passed to {@see sprintf()} with the inflected string
-     * if given.
+     * @param mixed ...$values Passed to {@see sprintf()} with the inflected
+     * string if given.
      */
     public static function format(string $format, int $count, ...$values): string
     {
-        return self::doFormat($format, $count, false, ...$values);
+        return self::doFormat($format, $count, [], false, ...$values);
     }
 
     /**
      * Inflect placeholders in a string in the singular if a count is 0 or 1, or
      * in the plural otherwise
      *
-     * @param mixed ...$values Passed to {@see sprintf()} with the inflected string
-     * if given.
+     * @param mixed ...$values Passed to {@see sprintf()} with the inflected
+     * string if given.
      */
     public static function formatWithSingularZero(string $format, int $count, ...$values): string
     {
-        return self::doFormat($format, $count, true, ...$values);
+        return self::doFormat($format, $count, [], true, ...$values);
     }
 
     /**
+     * @param array<string,(Closure(string|null): string)|string> $replace
      * @param mixed ...$values
      */
-    private static function doFormat(string $format, int $count, bool $zeroIsSingular, ...$values): string
+    private static function doFormat(string $format, int $count, array $replace, bool $zeroIsSingular, ...$values): string
     {
         $zero = $count === 0;
         $singular = $count === 1 || ($zero && $zeroIsSingular);
@@ -72,8 +145,9 @@ private static function doFormat(string $format, int $count, bool $zeroIsSingula
             $no = 'no';
         }
 
-        $replace = $singular
+        $replace = array_replace($singular
             ? [
+                '#' => (string) $count,
                 '' => $no ?? (string) $count,
                 'no' => $no ?? (string) $count,
                 'a' => $no ?? 'a',
@@ -86,6 +160,7 @@ private static function doFormat(string $format, int $count, bool $zeroIsSingula
                 'were' => 'was',
             ]
             : [
+                '#' => (string) $count,
                 '' => (string) $count,
                 'no' => $no ?? (string) $count,
                 'a' => $no ?? (string) $count,
@@ -96,18 +171,29 @@ private static function doFormat(string $format, int $count, bool $zeroIsSingula
                 'have' => 'have',
                 'was' => 'were',
                 'were' => 'were',
-            ];
+            ], $replace);
 
         $format = Pcre::replaceCallback(
-            '/\{\{#(?::(?<word>[a-z]++(?:(?:\h++|-)[a-z]++)*+)(?::(?<plural_word>[a-z]++(?:(?:\h++|-)[a-z]++)*+))?)?\}\}/i',
+            '/\{\{#(?::(?<word>[-a-z0-9_\h]*+|#)(?::(?<plural_word>[-a-z0-9_\h]*+))?)?\}\}/i',
             function (array $match) use ($singular, $replace): string {
-                $word = $match['word'] ?? '';
-                return $replace[Str::lower($word)]
+                $word = $match['word'];
+                $plural = $match['plural_word'];
+                if ($word === '') {
+                    return $singular ? '' : (string) $plural;
+                }
+                $word ??= (string) $word;
+                $word = Get::value($replace[Str::lower($word)]
                     ?? ($singular
                         ? $word
-                        : $match['plural_word'] ?? self::plural($word));
+                        : ($plural ?? self::plural($word))), $plural);
+                return $word === $match['word'] || $match['word'] === null
+                    ? $word
+                    : Str::matchCase($word, $match['word']);
             },
             $format,
+            -1,
+            $count,
+            \PREG_UNMATCHED_AS_NULL,
         );
 
         if ($values) {
diff --git a/src/Utility/Str.php b/src/Utility/Str.php
@@ -57,6 +57,40 @@ public static function upperFirst(string $string): string
         return $string;
     }
 
+    /**
+     * Match an ASCII string's case to another string
+     */
+    public static function matchCase(string $string, string $match): string
+    {
+        $match = trim($match);
+
+        if ($match === '') {
+            return $string;
+        }
+
+        $upper = strpbrk($match, Char::ALPHABETIC_UPPER);
+        $hasUpper = $upper !== false;
+        $hasLower = strpbrk($match, Char::ALPHABETIC_LOWER) !== false;
+
+        if ($hasUpper && !$hasLower && strlen($match) > 1) {
+            return self::upper($string);
+        }
+
+        if (!$hasUpper && $hasLower) {
+            return self::lower($string);
+        }
+
+        if (
+            // @phpstan-ignore-next-line
+            (!$hasUpper && !$hasLower) ||
+            $upper !== $match
+        ) {
+            return $string;
+        }
+
+        return self::upperFirst(self::lower($string));
+    }
+
     /**
      * Apply an end-of-line sequence to a string
      */
diff --git a/tests/unit/Utility/GetTest.php b/tests/unit/Utility/GetTest.php
@@ -54,6 +54,33 @@ public static function booleanProvider(): array
         ];
     }
 
+    /**
+     * @dataProvider integerProvider
+     *
+     * @param mixed $value
+     */
+    public function testInteger(?int $expected, $value): void
+    {
+        $this->assertSame($expected, Get::integer($value));
+    }
+
+    /**
+     * @return array<string,array{int|null,mixed}>
+     */
+    public static function integerProvider(): array
+    {
+        return [
+            'null' => [null, null],
+            'false' => [0, false],
+            'true' => [1, true],
+            '5' => [5, 5],
+            '5.5' => [5, 5.5],
+            "'5'" => [5, '5'],
+            "'5.5'" => [5, '5.5'],
+            "'foo'" => [0, 'foo'],
+        ];
+    }
+
     /**
      * @dataProvider apparentProvider
      *
@@ -99,6 +126,7 @@ public function testApparentWithInvalidValue(): void
     {
         $this->expectException(InvalidArgumentException::class);
         $this->expectExceptionMessage('Argument #1 ($value) must be of type int|float|string|bool|null, stdClass given');
+        // @phpstan-ignore-next-line
         Get::apparent(new stdClass());
     }
 
diff --git a/tests/unit/Utility/InflectTest.php b/tests/unit/Utility/InflectTest.php
diff --git a/tests/unit/Utility/StrTest.php b/tests/unit/Utility/StrTest.php
