Merge branch 'review-clioption-value-name'

Author: lkrms

composer.json

@@ -4,7 +4,7 @@
     "license": "MIT",
     "description": "A lightweight PHP toolkit for expressive backend/CLI apps",
     "require": {
-        "php": ">=7.4 <8.3",
+        "php": ">=7.4",
         "composer-runtime-api": "^2.2",
         "filp/whoops": "^2",
         "lkrms/dice": "^4.1.6",

src/Cli/CliOption.php

@@ -18,6 +18,7 @@
 use Lkrms\Contract\IReadable;
 use Lkrms\Facade\Assert;
 use Lkrms\Facade\Console;
+use Lkrms\Support\Catalog\CharacterSequence as Char;
 use Lkrms\Utility\Convert;
 use Lkrms\Utility\Env;
 use Lkrms\Utility\Test;
@@ -327,7 +328,7 @@ public function __construct(
         $this->Short = $this->IsPositional ? null : ($short ?: null);
         $this->Key = $this->IsPositional ? $long : ($short . '|' . $long);
         $this->ValueName = $this->IsFlag ? null : ($valueName ?: ($this->IsPositional ? Convert::toSnakeCase($long, '=') : null) ?: 'value');
-        $this->DisplayName = $this->IsPositional ? $this->getFriendlyValueName() : ($long ? '--' . $long : '-' . $short);
+        $this->DisplayName = $this->IsPositional ? $this->getFriendlyValueName(false) : ($long ? '--' . $long : '-' . $short);
         $this->ValueType = $this->IsFlag ? ($multipleAllowed ? CliOptionValueType::INTEGER : CliOptionValueType::BOOLEAN) : $valueType;
         $this->Delimiter = $multipleAllowed && !$this->IsFlag ? $delimiter : null;
         $this->Description = $description;
@@ -411,16 +412,28 @@ public function getNames(): array
     /**
      * Format the option's value name
      *
+     * If {@see CliOption::$ValueName} contains angle brackets (`<`, `>`), it is
+     * returned as-is, otherwise:
+     *
+     * - if it contains uppercase characters and no lowercase characters, it is
+     *   converted to kebab-case and capitalised
+     * - if not, it is converted to kebab-case and enclosed between angle
+     *   brackets
+     *
+     * In conversions to kebab-case, `=` is preserved.
      */
-    public function getFriendlyValueName(): ?string
+    public function getFriendlyValueName(bool $withMarkup = true): ?string
     {
-        $name = $this->ValueName;
-        $upper = $name === strtoupper($name);
-        $name = Convert::toKebabCase($name, '=');
-        if ($upper) {
-            return '<' . strtoupper($name) . '>';
+        if ($this->ValueName === null || strpbrk($this->ValueName, '<>') !== false) {
+            return $this->ValueName;
+        }
+
+        if (strpbrk($this->ValueName, Char::ALPHABETIC_UPPER) !== false &&
+                strpbrk($this->ValueName, Char::ALPHABETIC_LOWER) === false) {
+            [$before, $after] = $withMarkup ? ['<', '>'] : ['', ''];
+            return $before . strtoupper(Convert::toKebabCase($this->ValueName, '=')) . $after;
         }
-        return "<$name>";
+        return '<' . Convert::toKebabCase($this->ValueName, '=') . '>';
     }
 
     /**

src/Cli/CliOptionBuilder.php

@@ -15,7 +15,7 @@
  * @method static $this build(?IContainer $container = null) Create a new CliOptionBuilder (syntactic sugar for 'new CliOptionBuilder()')
  * @method $this long(?string $value) The long form of the option, e.g. 'verbose' (see {@see CliOption::$Long})
  * @method $this short(?string $value) The short form of the option, e.g. 'v' (see {@see CliOption::$Short})
- * @method $this valueName(?string $value) The name of the option's value as it appears in help messages (see {@see CliOption::$ValueName})
+ * @method $this valueName(?string $value) The name of the option's value as it appears in usage information (see {@see CliOption::$ValueName})
  * @method $this description(?string $value) A description of the option (see {@see CliOption::$Description})
  * @method $this optionType(CliOptionType::* $value) The option's type (see {@see CliOption::$OptionType})
  * @method $this valueType(CliOptionValueType::* $value) The data type of the option's value (see {@see CliOption::$ValueType})

src/Facade/Compute.php

@@ -3,6 +3,7 @@
 namespace Lkrms\Facade;
 
 use Lkrms\Concept\Facade;
+use Lkrms\Support\Catalog\CharacterSequence as Char;
 use Lkrms\Utility\Computations;
 
 /**
@@ -14,7 +15,7 @@
  * @method static void unload() Clear the underlying Computations instance
  * @method static string binaryHash(...$value) Generate a unique non-crypto hash and return raw binary data
  * @method static string hash(...$value) Generate a unique non-crypto hash and return a hexadecimal string
- * @method static string randomText(int $length, string $chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789') Generate a cryptographically secure string
+ * @method static string randomText(int $length, string $chars = Char::ALPHANUMERIC) Generate a cryptographically secure string
  * @method static float textDistance(string $string1, string $string2, bool $normalise = true) Returns the Levenshtein distance between two strings relative to the length of the longest string (see {@see Computations::textDistance()})
  * @method static float textSimilarity(string $string1, string $string2, bool $normalise = true) Returns the similarity of two strings relative to the length of the longest string (see {@see Computations::textSimilarity()})
  * @method static string uuid(bool $binary = false) Generate a cryptographically secure random UUID (see {@see Computations::uuid()})

src/Support/Catalog/CharacterSequence.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types=1);
+
+namespace Lkrms\Support\Catalog;
+
+use Lkrms\Concept\Dictionary;
+
+/**
+ * Character sequences
+ *
+ * @extends Dictionary<string>
+ */
+final class CharacterSequence extends Dictionary
+{
+    public const ALPHABETIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+    public const ALPHABETIC_LOWER = 'abcdefghijklmnopqrstuvwxyz';
+
+    public const ALPHABETIC_UPPER = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+
+    public const NUMERIC = '0123456789';
+
+    public const ALPHANUMERIC = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+}

src/Utility/Computations.php

@@ -2,6 +2,7 @@
 
 namespace Lkrms\Utility;
 
+use Lkrms\Support\Catalog\CharacterSequence as Char;
 use Lkrms\Utility\Convert;
 
 /**
@@ -41,7 +42,7 @@ public function uuid(bool $binary = false): string
      * Generate a cryptographically secure string
      *
      */
-    public function randomText(int $length, string $chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'): string
+    public function randomText(int $length, string $chars = Char::ALPHANUMERIC): string
     {
         $max = strlen($chars) - 1;
         $text = '';