feat: support add multi alises for an option

Author: inhere

README.md

@@ -17,6 +17,7 @@ Generic PHP command line flags parse library
 
 - Generic command line options and arguments parser.
 - Support set value data type(`int,string,bool,array`), will auto format input value.
+- Support set multi alias names for an option.
 - Support set multi short names for an option.
 - Support set default value for option/argument.
 - Support read flag value from ENV var.

README.zh-CN.md

@@ -18,6 +18,7 @@
 - 通用的命令行选项和参数解析器
 - 支持设置值数据类型(`int,string,bool,array`)，将自动格式化输入值
 - 支持为选项/参数设置默认值
+- 支持为一个选项设置多个别名
 - 支持为一个选项设置多个短名称
 - 支持从环境变量读取标志值
 - 支持设置选项/参数为必须的(`required`)

src/Concern/HelperRenderTrait.php

@@ -11,6 +11,7 @@
 use Toolkit\Stdlib\Helper\DataHelper;
 use Toolkit\Stdlib\Helper\IntHelper;
 use Toolkit\Stdlib\Str;
+use function array_push;
 use function array_shift;
 use function count;
 use function explode;
@@ -79,7 +80,7 @@ trait HelperRenderTrait
     /**
      * Will call it on before print help message
      *
-     * @var callable
+     * @var callable(string): string
      */
     private $beforePrintHelp;
 
@@ -298,9 +299,9 @@ protected function buildOptsForHelp(array $optDefines, bool $hasShortOpt): array
             }
 
             $names = $opt['shorts'];
-            /** @see Option support alias name. */
-            if (isset($opt['alias']) && $opt['alias']) {
-                $names[] = $opt['alias'];
+            // support multi alias names.
+            if (isset($opt['aliases']) && $opt['aliases']) {
+                array_push($names, ...$opt['aliases']);
             }
 
             // option name.
@@ -472,7 +473,7 @@ public function setExampleHelp($exampleHelp): void
     }
 
     /**
-     * @param callable $beforePrintHelp
+     * @param callable(string): string $beforePrintHelp
      */
     public function setBeforePrintHelp(callable $beforePrintHelp): void
     {

src/Concern/RuleParserTrait.php

@@ -142,7 +142,7 @@ public function addArgsByRules(array $rules): void
     /**
      * Add and argument by rule
      *
-     * @param string|int $name
+     * @param string $name
      * @param string|array $rule please see {@see argRules}
      *
      * @return $this
@@ -251,10 +251,11 @@ protected function parseRule($rule, string $name = '', int $index = 0, bool $isO
         $name = $name ?: $item['name'];
         if ($isOption) {
             // parse option name.
-            [$name, $shorts] = $this->parseRuleOptName($name);
+            [$name, $shorts, $aliases] = $this->parseRuleOptName($name);
 
-            // save alias
-            $item['shorts'] = $shorts ?: $shortsFromRule;
+            // save shorts and aliases
+            $item['shorts']  = $shorts ?: $shortsFromRule;
+            $item['aliases'] = $aliases;
         } else {
             $item['index'] = $index;
         }
@@ -268,7 +269,7 @@ protected function parseRule($rule, string $name = '', int $index = 0, bool $isO
      *
      * @param string $key 'lang,s' => option name is 'lang', alias 's'
      *
-     * @return array [name, shorts]
+     * @return array{string, array, array} [name, shorts, aliases]
      */
     protected function parseRuleOptName(string $key): array
     {
@@ -278,26 +279,34 @@ protected function parseRuleOptName(string $key): array
         }
 
         // only name.
-        if (strpos($key, ',') === false) {
+        if (!str_contains($key, ',')) {
             $name = ltrim($key, '-');
-            return [$name, []];
+            return [$name, [], []];
         }
 
         $name = '';
         $keys = Str::explode($key, ',');
 
-        // TIP: first is the option name. remaining is shorts.
-        $shorts = [];
+        $shorts = $aliases = [];
         foreach ($keys as $k) {
             // support like '--name, -n'
             $k = ltrim($k, '-');
 
-            // long string as option name.
-            if (!$name && strlen($k) > 1) {
-                $name = $k;
+            // max length string as option name.
+            if (($kl = strlen($k)) > 1) {
+                if (!$name ) {
+                    $name = $k;
+                } elseif ($kl > strlen($name)) {
+                    $aliases[] = $name;
+                    // update name
+                    $name = $k;
+                } else {
+                    $aliases[] = $k;
+                }
                 continue;
             }
 
+            // one char, as shorts
             $shorts[] = $k;
         }
 
@@ -306,7 +315,7 @@ protected function parseRuleOptName(string $key): array
             $name = array_shift($shorts);
         }
 
-        return [$name, $shorts];
+        return [$name, $shorts, $aliases];
     }
 
     /**

src/Flag/Option.php

@@ -28,18 +28,18 @@
 class Option extends AbstractFlag
 {
     /**
-     * alias name
+     * Shortcuts of the option. eg: ['a', 'b']
      *
-     * @var string
+     * @var array
      */
-    private $alias = '';
+    private $shorts = [];
 
     /**
-     * Shortcuts of the option. eg: ['a', 'b']
+     * alias names
      *
-     * @var array
+     * @var string[]
      */
-    private $shorts = [];
+    private $aliases = [];
 
     /**
      * Shortcuts of the option, string format. eg: 'a|b'
@@ -62,11 +62,21 @@ public function isBoolean(): bool
     }
 
     /**
-     * @return string
+     * @return string[]
      */
-    public function getAlias(): string
+    public function getAliases(): array
     {
-        return $this->alias;
+        return $this->aliases;
+    }
+
+    /**
+     * @param string[] $aliases
+     */
+    public function setAliases(array $aliases): void
+    {
+        foreach ($aliases as $alias) {
+            $this->setAlias($alias);
+        }
     }
 
     /**
@@ -86,7 +96,7 @@ public function setAlias(string $alias): void
             throw new FlagException('flag option alias length cannot be < 2 ');
         }
 
-        $this->alias = $alias;
+        $this->aliases[] = $alias;
     }
 
     /**
@@ -146,11 +156,8 @@ public function getDesc(bool $forHelp = false): string
      */
     public function getHelpName(): string
     {
-        $longs = [];
-        if ($this->alias) {
-            $longs[] = $this->alias;
-        }
-
+        $longs = $this->aliases;
+        // append name
         $longs[] = $this->name;
 
         // prepend '--'
@@ -188,8 +195,9 @@ public function toArray(): array
     {
         $info = parent::toArray();
 
-        $info['alias']  = $this->alias;
-        $info['shorts'] = $this->shorts;
+        $info['aliases'] = $this->aliases;
+        $info['shorts']  = $this->shorts;
         return $info;
     }
+
 }

src/Flags.php

@@ -340,7 +340,7 @@ protected function setOptValue(string $name, $value): bool
     {
         $name = $this->resolveAlias($name);
         if (!isset($this->options[$name])) {
-            throw new FlagException("flag option provided but not defined: $name", 404);
+            throw new FlagException("cannot set value for not defined option: $name", 404);
         }
 
         $this->options[$name]->setValue($value);
@@ -759,7 +759,7 @@ protected function resetArguments(): void
      * @param mixed  $default
      * @param array  $moreInfo
      *
-     * @psalm-param array{alias: string, helpType: string} $moreInfo
+     * @psalm-param array{aliases: array, helpType: string} $moreInfo
      *
      * @return ParserInterface|self
      */
@@ -774,7 +774,7 @@ public function addOpt(
     ): ParserInterface {
         /** @var Option $opt */
         $opt = Option::new($name, $desc, $type, $required, $default);
-        $opt->setAlias($moreInfo['alias'] ?? '');
+        $opt->setAliases($moreInfo['aliases'] ?? []);
         $opt->setShortcut($shortcut);
 
         $this->addOption($opt);
@@ -797,8 +797,8 @@ public function addOptByRule(string $name, $rule): FlagsParser
         /** @var Option $option */
         $option = Option::newByArray($define['name'], $define);
 
-        if (is_array($rule) && isset($rule['alias'])) {
-            $option->setAlias($rule['alias']);
+        if (is_array($rule) && isset($rule['aliases'])) {
+            $option->setAliases($rule['aliases']);
         }
 
         parent::addOptByRule($name, $rule);
@@ -831,13 +831,15 @@ public function addOption(Option $option): self
             throw new FlagException('cannot repeat add option: ' . $name);
         }
 
-        // has alias
-        if ($alias = $option->getAlias()) {
-            if (isset($this->options[$alias])) {
-                throw new FlagException("cannot assign alias '$alias' to option '$name', '$alias' is exists option");
-            }
+        // has aliases
+        if ($aliases = $option->getAliases()) {
+            foreach ($aliases as $alias) {
+                if (isset($this->options[$alias])) {
+                    throw new FlagException("cannot assign alias '$alias' to option '$name', '$alias' is exists option");
+                }
 
-            $this->setAlias($name, $alias, true);
+                $this->setAlias($name, $alias, true);
+            }
         }
 
         // has shorts

src/FlagsParser.php

@@ -62,6 +62,7 @@ abstract class FlagsParser implements ParserInterface
         'envVar'    => '', // support read value from ENV var
         'default'   => null,
         'shorts'    => [], // only for option. ['a', 'b']
+        'aliases'   => [], // only for option. ['cd', 'ef']
         'hidden'    => false, // only for option
         // value validator
         'validator' => null,

src/SFlags.php

@@ -495,7 +495,7 @@ protected function setOptValue(string $option, $value): void
     {
         $option = $this->resolveAlias($option);
         if (!isset($this->optDefines[$option])) {
-            throw new FlagException("flag option provided but not defined: $option", 404);
+            throw new FlagException("cannot set value for not defined option: $option", 404);
         }
 
         $define = $this->optDefines[$option];
@@ -696,6 +696,13 @@ protected function addOptDefine(array $define): void
             $this->opts[$name] = FlagType::fmtBasicTypeValue($type, $envVal);
         }
 
+        // has shorts
+        if ($define['aliases']) {
+            foreach ($define['aliases'] as $alias) {
+                $this->setAlias($name, $alias, true);
+            }
+        }
+
         // has shorts
         if ($define['shorts']) {
             foreach ($define['shorts'] as $short) {

test/Concern/RuleParserTest.php

@@ -4,6 +4,7 @@
 
 use Toolkit\PFlagTest\BaseFlagsTestCase;
 use Toolkit\PFlagTest\RuleParser;
+use function vdump;
 
 /**
  * class RuleParserTest
@@ -40,4 +41,15 @@ public function testParseRule_string(): void
         $this->assertSame(['23', '45'], $define['default']);
     }
 
+
+    public function testParseRule_string_hasAliases(): void
+    {
+        $p = RuleParser::new();
+
+        $define = $p->parseOpt('this is an string', '-t, --tpl, --tpl-file');
+
+        $this->assertEquals('tpl-file', $define['name']);
+        $this->assertEquals(['tpl'], $define['aliases']);
+        $this->assertEquals(['t'], $define['shorts']);
+    }
 }

test/Flag/OptionTest.php

@@ -18,12 +18,12 @@ public function testBasic(): void
         $this->assertFalse($opt->hasDefault());
         $this->assertFalse($opt->hasValue());
 
-        $opt->setAlias('n1');
-        $this->assertSame('n1', $opt->getAlias());
-        $this->assertSame('--n1, --name', $opt->getHelpName());
+        $opt->setAliases(['n1', 'n2']);
+        $this->assertSame(['n1', 'n2'], $opt->getAliases());
+        $this->assertSame('--n1, --n2, --name', $opt->getHelpName());
 
         $opt->setShortcut('n');
-        $this->assertSame('-n, --n1, --name', $opt->getHelpName());
+        $this->assertEquals('-n, --n1, --n2, --name', $opt->getHelpName());
 
         $opt->setDefault(89);
         $this->assertTrue($opt->hasDefault());