update: add more tests for parse flags

Author: inhere

README.md

@@ -203,7 +203,7 @@ $flags = ['--name', 'inhere', '--age', '99', '--tag', 'php', '-t', 'go', '--tag'
 
 $optRules = [
     'name', // string
-    'age'   => 'int;;required', // set required
+    'age'   => 'int;an int option;required', // set required
     'tag,t' => FlagType::ARRAY,
     'f'     => FlagType::BOOL,
 ];
@@ -251,7 +251,7 @@ $scriptFile = array_shift($rawFlags);
 $optRules = [
     // some option rules
     'name', // string
-    'age'   => 'int;;required', // set required
+    'age'   => 'int;an int option;required', // set required
     'tag,t' => FlagType::ARRAY,
     'f'     => FlagType::BOOL,
 ];
@@ -374,7 +374,9 @@ public const DEFINE_ITEM = [
 ];
 ```
 
-## Costom Settings
+## Costom settings
+
+### Settings for parse
 
 ```php
     // -------------------- settings for parse option --------------------
@@ -401,14 +403,67 @@ public const DEFINE_ITEM = [
     // -------------------- settings for parse argument --------------------
 
     /**
+     * Whether auto bind remaining args after option parsed
+     *
      * @var bool
      */
     protected $autoBindArgs = true;
 
     /**
+     * Strict match args number.
+     * if exist unbind args, will throw FlagException
+     *
      * @var bool
      */
-    protected $strictCheckArgs = false;
+    protected $strictMatchArgs = false;
+
+```
+
+### Setting for render help
+
+support some settings for render help
+
+```php
+
+    // -------------------- settings for built-in render help --------------------
+
+    /**
+     * Auto render help on provide '-h', '--help'
+     *
+     * @var bool
+     */
+    protected $autoRenderHelp = true;
+
+    /**
+     * Show flag data type on render help.
+     *
+     * if False:
+     *
+     * -o, --opt    Option desc
+     *
+     * if True:
+     *
+     * -o, --opt STRING   Option desc
+     *
+     * @var bool
+     */
+    protected $showTypeOnHelp = true;
+
+    /**
+     * Will call it on before print help message
+     *
+     * @var callable
+     */
+    private $beforePrintHelp;
+
+```
+
+- custom help message renderer
+
+```php
+$fs->setHelpRenderer(function (\Toolkit\PFlag\FlagsParser $fs) {
+    // render help messages
+});
 ```
 
 ## Unit tests

src/Concern/HelperRenderTrait.php

@@ -29,23 +29,13 @@
  */
 trait HelperRenderTrait
 {
-
     /**
      * Custom help renderer.
      *
      * @var callable
      */
     protected $helpRenderer;
 
-    /**
-     * Auto render help on provide '-h', '--help'
-     *
-     * @var bool
-     */
-    protected $autoRenderHelp = true;
-
-    // -------------------- settings for built-in render help --------------------
-
     /**
      * @var string|array|null
      */
@@ -56,14 +46,33 @@ trait HelperRenderTrait
      */
     protected $exampleHelp = '';
 
+    // -------------------- settings for built-in render help --------------------
+
+    /**
+     * Auto render help on provide '-h', '--help'
+     *
+     * @var bool
+     */
+    protected $autoRenderHelp = true;
+
     /**
-     * Show flag data type on render help
+     * Show flag data type on render help.
+     *
+     * if False:
+     *
+     * -o, --opt    Option desc
+     *
+     * if True:
+     *
+     * -o, --opt STRING   Option desc
      *
      * @var bool
      */
     protected $showTypeOnHelp = true;
 
     /**
+     * Will call it on before print help message
+     *
      * @var callable
      */
     private $beforePrintHelp;
@@ -383,7 +392,9 @@ public function getMoreHelp()
      */
     public function setMoreHelp($moreHelp): void
     {
-        $this->moreHelp = $moreHelp;
+        if ($moreHelp) {
+            $this->moreHelp = $moreHelp;
+        }
     }
 
     /**
@@ -407,7 +418,9 @@ public function setExample($example): void
      */
     public function setExampleHelp($exampleHelp): void
     {
-        $this->exampleHelp = $exampleHelp;
+        if ($exampleHelp) {
+            $this->exampleHelp = $exampleHelp;
+        }
     }
 
     /**

src/Concern/RuleParserTrait.php

@@ -255,18 +255,6 @@ protected function parseRule($rule, string $name = '', int $index = 0, bool $isO
             $item['index'] = $index;
         }
 
-        $nameMark = $name ? "(name: $name)" : "(#$index)";
-
-        // check type
-        if (!FlagType::isValid($type = $item['type'])) {
-            throw new FlagException("cannot define invalid flag type: $type$nameMark");
-        }
-
-        // validator must be callable
-        if (!empty($item['validator']) && !is_callable($item['validator'])) {
-            throw new InvalidArgumentException("validator must be callable. flag: $nameMark");
-        }
-
         $item['name'] = $name;
         return $item;
     }

src/Contract/FlagInterface.php

@@ -52,6 +52,11 @@ public function getValue();
      */
     public function setValue($value): void;
 
+    /**
+     * @param mixed $value
+     */
+    public function setTrustedValue($value): void;
+
     /**
      * @return bool
      */

src/Contract/ParserInterface.php

@@ -141,6 +141,14 @@ public function hasArg($nameOrIndex): bool;
      */
     public function getArg($nameOrIndex, $default = null);
 
+    /**
+     * @param string|int $nameOrIndex
+     * @param mixed $value
+     *
+     * @return mixed
+     */
+    // TODO public function setArg($nameOrIndex, $value): void;
+
     /**
      * @return array
      * @psalm-return array<string, mixed>
@@ -176,4 +184,14 @@ public function isLocked(): bool;
     public function lock(): void;
 
     public function unlock(): void;
+
+    /**
+     * @param mixed $value
+     */
+    // TODO public function setTrustedOpt(string $name, $value): void;
+
+    /**
+     * @param mixed $value
+     */
+    // TODO public function setTrustedArg(string $name, $value): void;
 }

src/Flag/AbstractFlag.php

@@ -183,6 +183,14 @@ public function getValue()
         return $this->value;
     }
 
+    /**
+     * @param mixed $value
+     */
+    public function setTrustedValue($value): void
+    {
+        $this->value = $value;
+    }
+
     /**
      * @param mixed $value
      */
@@ -274,8 +282,9 @@ public function setType(string $type): void
         }
 
         if (!FlagType::isValid($type)) {
+            $kind = $this->getKind();
             $name = $this->getNameMark();
-            throw new FlagException("cannot define invalid flag type: $type $name");
+            throw new FlagException("invalid flag type '$type', $kind: $name");
         }
 
         $this->type = $type;
@@ -295,8 +304,7 @@ public function getName(): string
     public function setName(string $name): void
     {
         if (!FlagHelper::isValidName($name)) {
-            $kind = $this->getKind();
-            throw new FlagException("invalid flag $kind name: " . $name);
+            throw new FlagException("invalid flag option name: $name");
         }
 
         $this->name = $name;

src/Flag/Argument.php

@@ -9,6 +9,8 @@
 
 namespace Toolkit\PFlag\Flag;
 
+use Toolkit\Cli\Helper\FlagHelper;
+use Toolkit\PFlag\Exception\FlagException;
 use Toolkit\PFlag\FlagsParser;
 use Toolkit\Stdlib\Str;
 use function sprintf;
@@ -34,7 +36,12 @@ class Argument extends AbstractFlag
     public function setName(string $name): void
     {
         if ($name) {
-            parent::setName($name);
+            if (!FlagHelper::isValidName($name)) {
+                $mark = sprintf('#%d(%s)', $this->index, $name);
+                throw new FlagException("invalid flag argument name: $mark");
+            }
+
+            $this->name = $name;
         }
     }
 

src/Flags.php

@@ -406,7 +406,7 @@ public function bindingArguments(): self
             }
         }
 
-        if ($this->strictCheckArgs && $args) {
+        if ($this->strictMatchArgs && $args) {
             throw new FlagException(sprintf('unknown arguments (error: "%s").', implode(' ', $args)));
         }
 

src/FlagsParser.php

@@ -147,7 +147,7 @@ abstract class FlagsParser implements ParserInterface
      *
      * @var bool
      */
-    protected $delayValidate = false;
+    // protected $delayValidate = false;
 
     // -------------------- settings for parse option --------------------
 
@@ -183,14 +183,19 @@ abstract class FlagsParser implements ParserInterface
     // -------------------- settings for parse argument --------------------
 
     /**
+     * Whether auto bind remaining args after option parsed
+     *
      * @var bool
      */
     protected $autoBindArgs = true;
 
     /**
+     * Strict match args number.
+     * if exist unbind args, will throw FlagException
+     *
      * @var bool
      */
-    protected $strictCheckArgs = false;
+    protected $strictMatchArgs = false;
 
     /**
      * Has array argument
@@ -371,10 +376,18 @@ public function getDesc(): string
 
     /**
      * @param string $desc
+     * @param bool $setOnEmpty only set on desc is empty
      */
-    public function setDesc(string $desc): void
+    public function setDesc(string $desc, bool $setOnEmpty = false): void
     {
-        $this->desc = $desc;
+        // only set on desc is empty
+        if ($setOnEmpty && $this->desc) {
+            return;
+        }
+
+        if ($desc) {
+            $this->desc = $desc;
+        }
     }
 
     /**
@@ -510,17 +523,17 @@ public function setAutoBindArgs(bool $autoBindArgs): void
     /**
      * @return bool
      */
-    public function isStrictCheckArgs(): bool
+    public function isStrictMatchArgs(): bool
     {
-        return $this->strictCheckArgs;
+        return $this->strictMatchArgs;
     }
 
     /**
-     * @param bool $strictCheckArgs
+     * @param bool $strictMatchArgs
      */
-    public function setStrictCheckArgs(bool $strictCheckArgs): void
+    public function setStrictMatchArgs(bool $strictMatchArgs): void
     {
-        $this->strictCheckArgs = $strictCheckArgs;
+        $this->strictMatchArgs = $strictMatchArgs;
     }
 
     /**