enhance: support auto indent multi line text on command help

Author: inhere

src/AbstractApplication.php

@@ -347,6 +347,11 @@ public function stop(int $code = 0)
         exit($code);
     }
 
+    /**
+     * @param array $args
+     *
+     * @return int|mixed
+     */
     public function runWithArgs(array $args)
     {
         $this->input->setArgs($args);

src/Application.php

@@ -259,7 +259,7 @@ protected function getFileFilter(): callable
      ****************************************************************************/
 
     /**
-     * @param string $name
+     * @param string $name command name or command ID or command path.
      * @param array  $args
      *
      * @return int|mixed

src/Component/Formatter/Padding.php

@@ -4,8 +4,8 @@
 
 use Inhere\Console\Component\MessageFormatter;
 use Inhere\Console\Console;
-use Inhere\Console\Util\Helper;
 use Toolkit\Cli\ColorTag;
+use Toolkit\Stdlib\Arr\ArrayHelper;
 use Toolkit\Stdlib\Str;
 use function array_merge;
 use function trim;
@@ -45,7 +45,7 @@ public static function show(array $data, string $title = '', array $opts = []):
             'valueStyle' => 'info',
         ], $opts);
 
-        $keyMaxLen  = Helper::getKeyMaxWidth($data);
+        $keyMaxLen  = ArrayHelper::getKeyMaxWidth($data);
         $paddingLen = $keyMaxLen > $opts['padding'] ? $keyMaxLen : $opts['padding'];
 
         foreach ($data as $label => $value) {

src/Controller.php

@@ -507,7 +507,6 @@ protected function getMethodName(string $action): string
 
     /**
      * @return bool
-     * @throws ReflectionException
      */
     protected function showHelp(): bool
     {

src/Util/FormatUtil.php

@@ -9,12 +9,14 @@
 namespace Inhere\Console\Util;
 
 use Toolkit\Cli\ColorTag;
+use Toolkit\Stdlib\Arr\ArrayHelper;
 use Toolkit\Stdlib\Helper\Format;
 use Toolkit\Stdlib\Helper\JsonHelper;
 use Toolkit\Stdlib\Str;
 use Toolkit\Sys\Sys;
 use function array_keys;
 use function array_merge;
+use function array_shift;
 use function explode;
 use function implode;
 use function is_array;
@@ -200,18 +202,20 @@ public static function howLongAgo(int $secs): string
     /**
      * Splice array
      *
-     * @param array $data
-     *     e.g [
+     * ```php
+     * $data = [
      *     'system'  => 'Linux',
-     *     'version'  => '4.4.5',
-     *     ]
+     *     'version' => '4.4.5',
+     * ];
+     * ```
+     *
+     * @param array $data
      * @param array $opts
      *
      * @return string
      */
     public static function spliceKeyValue(array $data, array $opts = []): string
     {
-        $text = '';
         $opts = array_merge([
             'leftChar'    => '',   // e.g '  ', ' * '
             'sepChar'     => ' ',  // e.g ' | ' OUT: key | value
@@ -221,33 +225,37 @@ public static function spliceKeyValue(array $data, array $opts = []): string
             'keyMinWidth' => 8,
             'keyMaxWidth' => 0, // if not set, will automatic calculation
             'ucFirst'     => true,  // upper first char for value
+            'endNewline'  => true,  // with newline on end.
         ], $opts);
 
         if ($opts['keyMaxWidth'] < 1) {
-            $opts['keyMaxWidth'] = Helper::getKeyMaxWidth($data);
+            $opts['keyMaxWidth'] = ArrayHelper::getKeyMaxWidth($data);
         }
 
         // compare
-        if ((int)$opts['keyMinWidth'] > $opts['keyMaxWidth']) {
-            $opts['keyMaxWidth'] = $opts['keyMinWidth'];
+        if ($opts['keyMinWidth'] > $opts['keyMaxWidth']) {
+            $opts['keyMaxWidth'] = (int)$opts['keyMinWidth'];
         }
 
+        $keyWidth  = $opts['keyMaxWidth'];
         $keyStyle  = trim($opts['keyStyle']);
         $keyPadPos = (int)$opts['keyPadPos'];
 
+        $fmtLines = [];
         foreach ($data as $key => $value) {
-            $hasKey = !is_int($key);
-            $text   .= $opts['leftChar'];
+            $hasKey  = !is_int($key);
+            $fmtLine = $opts['leftChar'];
 
-            if ($hasKey && $opts['keyMaxWidth']) {
-                $key  = Str::pad((string)$key, $opts['keyMaxWidth'], ' ', $keyPadPos);
-                $text .= ColorTag::wrap($key, $keyStyle) . $opts['sepChar'];
+            if ($hasKey && $keyWidth) {
+                $strKey  = Str::pad((string)$key, $keyWidth, ' ', $keyPadPos);
+                $fmtLine .= ColorTag::wrap($strKey, $keyStyle) . $opts['sepChar'];
             }
 
+            $lines = [];
+
             // if value is array, translate array to string
             if (is_array($value)) {
                 $temp = '[';
-
                 foreach ($value as $k => $val) {
                     if (is_bool($val)) {
                         $val = $val ? '(True)' : '(False)';
@@ -261,14 +269,37 @@ public static function spliceKeyValue(array $data, array $opts = []): string
                 $value = rtrim($temp, ' ,') . ']';
             } elseif (is_bool($value)) {
                 $value = $value ? '(True)' : '(False)';
-            } else {
+            } else { // to string.
                 $value = (string)$value;
+
+                // multi line
+                if ($hasKey && strpos($value, "\n") > 0) {
+                    $lines = explode("\n", $value);
+                    $value = array_shift($lines);
+                }
             }
 
+            // uc-first
             $value = $hasKey && $opts['ucFirst'] ? ucfirst($value) : $value;
-            $text  .= ColorTag::wrap($value, $opts['valStyle']) . "\n";
+
+            // append value.
+            $fmtLine .= ColorTag::wrap($value, $opts['valStyle']);
+            // append fmt line.
+            $fmtLines[] = $fmtLine;
+
+            // value has multi line
+            if ($lines) {
+                $linePrefix = $opts['leftChar'] . Str::repeat(' ', $keyWidth + 1) . $opts['sepChar'];
+                foreach ($lines as $line) {
+                    $fmtLines[]  = $linePrefix . $line;
+                }
+            }
+        }
+
+        if ($opts['endNewline']) {
+            return implode("\n", $fmtLines) . "\n";
         }
 
-        return $text;
+        return implode("\n", $fmtLines);
     }
 }

src/Util/Helper.php

@@ -196,6 +196,7 @@ public static function findSimilar(string $need, $iterator, int $similarPercent
      * @param bool  $excludeInt
      *
      * @return int
+     * @deprecated please use ArrayHelper::getKeyMaxWidth($data, $excludeInt);
      */
     public static function getKeyMaxWidth(array $data, bool $excludeInt = true): int
     {