up: add more methods for render help

Author: inhere

example/flags-demo.php

@@ -71,6 +71,13 @@
 $arg->setDesc("this is an array arg,\n allow multi value,\n must define at last");
 $fs->addArgument($arg);
 
+$fs->setMoreHelp('more help message ...');
+
+$fs->setExampleHelp([
+    'example usage 1',
+    'example usage 2',
+]);
+
 // edump($fs);
 
 // do parsing

example/sflags-demo.php

@@ -40,6 +40,13 @@
 $fs->setOptRules($optRules);
 $fs->setArgRules($argRules);
 
+$fs->setMoreHelp('more help message ...');
+
+$fs->setExample([
+    'example usage 1',
+    'example usage 2',
+]);
+
 // do parsing
 try {
     if (!$fs->parse($flags)) {

src/Concern/HelperRenderTrait.php

@@ -30,8 +30,6 @@
 trait HelperRenderTrait
 {
 
-    // -------------------- settings for render help --------------------
-
     /**
      * Custom help renderer.
      *
@@ -46,12 +44,7 @@ trait HelperRenderTrait
      */
     protected $autoRenderHelp = true;
 
-    /**
-     * Show flag data type on render help
-     *
-     * @var bool
-     */
-    protected $showTypeOnHelp = true;
+    // -------------------- settings for built-in render help --------------------
 
     /**
      * @var string|array|null
@@ -63,6 +56,18 @@ trait HelperRenderTrait
      */
     protected $exampleHelp = '';
 
+    /**
+     * Show flag data type on render help
+     *
+     * @var bool
+     */
+    protected $showTypeOnHelp = true;
+
+    /**
+     * @var callable
+     */
+    private $beforePrintHelp;
+
     /**
      * @param array $argDefines
      * @param array $optDefines
@@ -147,21 +152,28 @@ protected function doBuildHelp(array $argDefines, array $optDefines, bool $withC
         }
 
         // --------------- extra: moreHelp, example -----------------
-        if ($this->moreHelp) {
-            $buf->writeln('<ylw>More Help:</ylw>');
+        if ($this->exampleHelp) {
+            $buf->writeln("\n<ylw>Examples:</ylw>");
 
-            $lines = is_array($this->moreHelp) ? $this->moreHelp : [$this->moreHelp];
+            $lines = is_array($this->exampleHelp) ? $this->exampleHelp : [$this->exampleHelp];
             $buf->writeln('  ' . implode("\n  ", $lines));;
         }
 
-        if ($this->exampleHelp) {
-            $buf->writeln('<ylw>Examples:</ylw>');
+        if ($this->moreHelp) {
+            $buf->writeln("\n<ylw>More Help:</ylw>");
 
-            $lines = is_array($this->exampleHelp) ? $this->exampleHelp : [$this->exampleHelp];
-            $buf->writeln('  ' . implode("\n  ", $lines));;
+            $lines = is_array($this->moreHelp) ? $this->moreHelp : [$this->moreHelp];
+            $buf->writeln('  ' . implode("\n  ", $lines));
         }
 
-        return $withColor ? $buf->clear() : ColorTag::clear($buf->clear());
+        // fire event
+        if ($fn = $this->beforePrintHelp) {
+            $text = $fn($buf->getAndClear());
+        } else {
+            $text = $buf->getAndClear();
+        }
+
+        return $withColor ? $text : ColorTag::clear($text);
     }
 
     /**
@@ -372,11 +384,27 @@ public function getExampleHelp()
         return $this->exampleHelp;
     }
 
+    /**
+     * @param array|string|null $example
+     */
+    public function setExample($example): void
+    {
+        $this->setExampleHelp($example);
+    }
+
     /**
      * @param array|string|null $exampleHelp
      */
     public function setExampleHelp($exampleHelp): void
     {
         $this->exampleHelp = $exampleHelp;
     }
+
+    /**
+     * @param callable $beforePrintHelp
+     */
+    public function setBeforePrintHelp(callable $beforePrintHelp): void
+    {
+        $this->beforePrintHelp = $beforePrintHelp;
+    }
 }

src/Contract/ParserInterface.php

@@ -24,6 +24,11 @@ public function getFlags(): array;
      */
     public function getRawArgs(): array;
 
+    /**
+     * @return bool
+     */
+    public function isNotEmpty(): bool;
+
     /**
      * @param array|null $flags
      *

src/Flags.php

@@ -434,6 +434,14 @@ public function toArray(): array
         ];
     }
 
+    /**
+     * @return bool
+     */
+    public function isNotEmpty(): bool
+    {
+        return count($this->options) > 0 || count($this->arguments) > 0;
+    }
+
     /**************************************************************************
      * arguments
      **************************************************************************/

src/SFlags.php

@@ -14,6 +14,7 @@
 use Toolkit\PFlag\Exception\FlagParseException;
 use Toolkit\Stdlib\OS;
 use Toolkit\Stdlib\Str;
+use function count;
 use function current;
 use function explode;
 use function implode;
@@ -128,6 +129,14 @@ public function buildHelp(bool $withColor = true): string
         return $this->doBuildHelp($this->argDefines, $this->optDefines, $withColor);
     }
 
+    /**
+     * @return bool
+     */
+    public function isNotEmpty(): bool
+    {
+        return count($this->optDefines) > 0 || count($this->argDefines) > 0;
+    }
+
     /****************************************************************
      * parse options and arguments
      ***************************************************************/