style: run code check by psalm tool

Author: inhere

README.md

@@ -173,7 +173,7 @@ array(3) {
 }
 ```
 
-## SFlags
+## SFlags Usage
 
 SFlags - is an simple flags(options&argument) parser and manager.
 

example/refer.php

@@ -0,0 +1,17 @@
+<?php
+
+$flags = ['--name', 'inhere', '--tags', 'php', '-t', 'go', '--tags', 'java', '-f', 'arg0'];
+echo "count: ", count($flags), "\n";
+
+$cur = current($flags);
+$key = key($flags);
+echo "key: $key, current: $cur\n";
+
+while (true) {
+    if (($key = key($flags)) === null) {
+        break;
+    }
+
+    $val = next($flags);
+    echo "key: $key, next: '$val'\n";
+}

psalm.xml

@@ -0,0 +1,18 @@
+<?xml version="1.0"?>
+<psalm
+        errorLevel="3"
+        resolveFromConfigFile="true"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xmlns="https://getpsalm.org/schema/config"
+        xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd"
+>
+    <projectFiles>
+        <directory name="src"/>
+        <ignoreFiles>
+            <directory name="test"/>
+<!--            <directory name="vendor"/>-->
+        </ignoreFiles>
+    </projectFiles>
+    <issueHandlers>
+    </issueHandlers>
+</psalm>

src/AbstractParser.php src/AbstractFlags.php

@@ -20,6 +20,7 @@
 use Toolkit\Stdlib\Str;
 use function array_merge;
 use function array_shift;
+use function array_values;
 use function basename;
 use function count;
 use function explode;
@@ -34,14 +35,15 @@
 use function trim;
 
 /**
- * class AbstractParser
+ * class AbstractFlags
+ * abstract parser
  */
-abstract class AbstractParser implements ParserInterface
+abstract class AbstractFlags implements ParserInterface
 {
     use QuickInitTrait;
     use NameAliasTrait;
 
-    protected const TRIM_CHARS = "; \t\n\r\0\x0B";
+    protected const TRIM_CHARS    = "; \t\n\r\0\x0B";
     protected const OPT_MAX_WIDTH = 16;
 
     public const RULE_SEP = ';';
@@ -50,7 +52,9 @@ abstract class AbstractParser implements ParserInterface
 
     public const STATUS_ERR = 1;
 
-    public const STATUS_HELP = 2; // found `-h|--help` flag
+    public const STATUS_ARG = 2;
+
+    public const STATUS_HELP = 3; // found `-h|--help` flag
 
     public const SHORT_STYLE_GUN = 'gnu';
 
@@ -148,7 +152,8 @@ abstract class AbstractParser implements ParserInterface
     protected $shortStyle = 'posix';
 
     /**
-     * Whether stop parse option on first argument
+     * Stop parse option on found first argument.
+     * - useful for support multi commands. eg: `top --opt ... sub --opt ...`
      *
      * @var bool
      */
@@ -198,6 +203,39 @@ public function __construct(array $config = [])
         Obj::init($this, $config);
     }
 
+    /**
+     * @param array|null $flags
+     *
+     * @return bool
+     */
+    public function parse(?array $flags = null): bool
+    {
+        if ($this->parsed) {
+            return true;
+        }
+
+        $this->parsed  = true;
+        $this->rawArgs = [];
+
+        if ($flags === null) {
+            $flags = $_SERVER['argv'];
+            $sFile = array_shift($flags);
+            $this->setScriptFile($sFile);
+        } else {
+            $flags = array_values($flags);
+        }
+
+        $this->flags = $flags;
+        return $this->doParse($flags);
+    }
+
+    /**
+     * @param array $flags
+     *
+     * @return bool
+     */
+    abstract protected function doParse(array $flags): bool;
+
     /**
      * @param array $rawArgs
      *
@@ -227,6 +265,13 @@ protected function parseRawArgs(array $rawArgs): array
         return $args;
     }
 
+    public function resetResults(): void
+    {
+        // clear match results
+        $this->parsed  = false;
+        $this->rawArgs = $this->flags = [];
+    }
+
     /****************************************************************
      * build and render help
      ***************************************************************/
@@ -346,10 +391,10 @@ protected function doBuildHelp(array $argDefines, array $optDefines, bool $withC
     }
 
     /**
-     * @see DEFINE_ITEM for array $define
      * @param array|Option|Argument $define
      *
      * @return array
+     * @see DEFINE_ITEM for array $define
      */
     protected function formatDesc($define): array
     {
@@ -403,7 +448,7 @@ protected function buildArgsForHelp(array $argDefines): array
             }
 
             // ensure desc is not empty
-            $arg['desc'] = $desc ? Str::ucfirst($desc): "Argument $helpName";
+            $arg['desc'] = $desc ? Str::ucfirst($desc) : "Argument $helpName";
 
             $type = $arg['type'];
             if (FlagType::isArray($type)) {
@@ -455,7 +500,7 @@ protected function buildOptsForHelp(array $optDefines): array
             }
 
             // ensure desc is not empty
-            $opt['desc'] = $desc ? Str::ucfirst($desc): "Option $name";
+            $opt['desc'] = $desc ? Str::ucfirst($desc) : "Option $name";
 
             $helpName = FlagUtil::buildOptHelpName($names);
             if ($this->showTypeOnHelp) {

src/Contract/ParserInterface.php

@@ -25,11 +25,18 @@ public function getFlags(): array;
     public function getRawArgs(): array;
 
     /**
-     * @param array $flags
+     * @param array|null $flags
      *
      * @return bool
      */
-    public function parse(array $flags): bool;
+    public function parse(?array $flags = null): bool;
+
+    /**
+     * @param string $name
+     *
+     * @return bool
+     */
+    public function hasOpt(string $name): bool;
 
     /**
      * Get an option value by name
@@ -41,6 +48,13 @@ public function parse(array $flags): bool;
      */
     public function getOpt(string $name, $default = null);
 
+    /**
+     * @param string|int $nameOrIndex
+     *
+     * @return bool
+     */
+    public function hasArg($nameOrIndex): bool;
+
     /**
      * Get an argument value by name
      *

src/Flag/AbstractFlag.php

@@ -81,7 +81,8 @@ abstract class AbstractFlag implements ArrayAccess, FlagInterface
      * The flag value validator
      * - if validate fail, please return for OR throw FlagException
      *
-     * @var callable|ValidatorInterface
+     * @var callable|ValidatorInterface|null
+     * @psalm-var callable(mixed, string): bool
      */
     protected $validator;