Add 'list' command padding settings to EnvironmentConfig.

Author: MagicPush

docs/features-manual.md

@@ -540,6 +540,52 @@ by `somewhere/launchers/launcher.php` main config.
 
 ### Available settings
 
+#### listPaddingLeftMain
+
+* Affects the padding from the left border of a terminal for `list` [built-in subcommand](#built-in-subcommands) output.
+  The padding precedes each line (headers and command names).
+
+    * The setting is ignored (treated as `0`) if `--slim` output mode is enabled.
+* Controls the padding size as the number of space characters.
+* Possible values: non-negative `int`.
+    * Values below `0` are silently treated as `0`.
+
+#### listPaddingLeftCommand
+
+* Affects the padding to the left of a command or subsequent header (in addition to
+  [listPaddingLeftMain](#listpaddingleftmain)) for `list` [built-in subcommand](#built-in-subcommands) output.
+
+    * The setting is ignored (treated as `0`) if `--slim` output mode is enabled.
+* Controls the padding size as the number of space characters.
+* Possible values: non-negative `int`.
+    * Values below `0` are silently treated as `0`.
+    
+Consider a command name `some:cool:command` with [listPaddingLeftMain](#listpaddingleftmain) = 1 and this setting = 4.
+The command contains 2 sections, so after the main header (the first section) 2 more lines will be shown - a subsection
+and a full command name:
+
+```
+# This line is added here as a reference - it does not have any left padding.
+ some:
+     some:cool:
+         some:cool:command
+```
+
+The first (main) header is padded with [listPaddingLeftMain](#listpaddingleftmain), however subsequent header and
+the command itself are additionally padded with this setting, `listPaddingLeftCommand`.
+
+#### listPaddingLeftCommandDescription
+
+* Affects the minimum left padding for all commands descriptions outputted with `list`
+  [built-in subcommand](#built-in-subcommands).
+  
+  The maximum padding depends on the longest command name "column", which consists of
+  [listPaddingLeftMain](#listpaddingleftmain), [listPaddingLeftCommand](#listpaddingleftcommand) for each section, and
+  the command full name (including name sections).
+* Controls the padding size as the number of space characters.
+* Possible values: non-negative `int`.
+    * Values below `0` are silently treated as `0`.
+
 #### helpGeneratorPaddingLeftMain
 
 * Affects the padding from the left border of a terminal. The padding precedes almost all lines from generated `help`
@@ -550,7 +596,10 @@ by `somewhere/launchers/launcher.php` main config.
 
 #### helpGeneratorPaddingLeftParameterDescription
 
-* Affects the left padding for parameters' descriptions.
+* Affects the minimum left padding for parameters' descriptions outputted on a generated `help` page.
+
+  The maximum padding depends on the longest parameter name "column", which consists of
+  [helpGeneratorPaddingLeftMain](#helpgeneratorpaddingleftmain) and a parameter formatted name.
 * Controls the padding size as the number of space characters.
 * Possible values: non-negative `int`.
     * Values below `0` are silently treated as `0`.

docs/todo.md

@@ -112,8 +112,7 @@ The list of plans and ideas for future development.
         - ~~making `getConfigBuilder()` non-static, creating `ConfigBuilder` instance inside `__construct()`.~~
     1. - [x] Make creating buildable instances that are expected to be called by users (like detectors)
          with `create` static methods.
-    1. - [ ] Move `ListSubcommands::PADDING_BLOCK` as 2 separate `EnvironmentConfig` settings - name and description
-       paddings.
+    1. - [x] Transform `ListSubcommands::PADDING_BLOCK` into separate `EnvironmentConfig` padding settings.
     1. - [ ] Place attributes after phpdoc blocks.
     1. - [x] Consider adding even more [backward incompatibilities](todo.md#next-major-release) ~~or delaying
        the next major release, see [already implemented backward incompatibilities](changelog.md#v300)~~.

src/Parametizer/EnvironmentConfig.php

@@ -15,6 +15,10 @@ class EnvironmentConfig {
 
     /* AVAILABLE PROPERTIES -> */
 
+    public int $listPaddingLeftMain               = 1;
+    public int $listPaddingLeftCommand            = 2;
+    public int $listPaddingLeftCommandDescription = 4;
+
     public int $helpGeneratorPaddingLeftMain                        = 2;
     public int $helpGeneratorPaddingLeftParameterDescription        = 4;
     public int $helpGeneratorShortDescriptionCharsMinBeforeFullStop = 40;

src/Parametizer/ScriptClass/BuiltinSubcommand/ListSubcommands.php

@@ -15,8 +15,6 @@
 use Override;
 
 class ListSubcommands extends BuiltinSubcommandAbstract {
-    protected const string PADDING_BLOCK = '    ';
-
     protected const string HEADER_DEFAULT = '--';
 
 
@@ -27,6 +25,10 @@ class ListSubcommands extends BuiltinSubcommandAbstract {
     protected readonly bool   $isSlim;
     protected readonly string $subcommandNamePart;
 
+    protected readonly int $paddingLeftMain;
+    protected readonly int $paddingLeftCommand;
+    protected readonly int $paddingLeftCommandDescription;
+
     #[Override]
     public static function getScriptInnerName(): string {
         return 'list';
@@ -58,6 +60,10 @@ public function __construct(CliRequest $request) {
 
         $this->isSlim             = $request->getParamAsBool('slim');
         $this->subcommandNamePart = $request->getParamAsString('subcommand-name-part');
+
+        $this->paddingLeftMain               = $this->isSlim ? 0 : max(0, $this->environmentConfig->listPaddingLeftMain);
+        $this->paddingLeftCommand            = max(0, $this->environmentConfig->listPaddingLeftCommand);
+        $this->paddingLeftCommandDescription = max(0, $this->environmentConfig->listPaddingLeftCommandDescription);
     }
 
     public function execute(): void {
@@ -89,7 +95,6 @@ public function execute(): void {
         $subcommandGroupsAuto = [];
 
         $subcommandNameColumnWidthMax = 0;
-        $padBlockWidth                = mb_strlen(static::PADDING_BLOCK);
         foreach ($this->parentConfig->getBranches() as $subcommandName => $subcommandConfig) {
             $isBuiltInSubcommand = array_key_exists($subcommandName, $builtInSubcommands);
 
@@ -111,8 +116,8 @@ public function execute(): void {
             } else {
                 $nodeLevel = mb_substr_count($subcommandName, static::NAME_SECTION_SEPARATOR);
             }
-            $subcommandNameColumnWidth = $padBlockWidth * max($this->isSlim ? 0 : 1, $nodeLevel)
-                + mb_strlen($subcommandName);
+            $subcommandNameColumnWidth = mb_strlen($subcommandName)
+                + $this->paddingLeftCommand * max($this->isSlim ? 0 : 1, $nodeLevel);
             if ($subcommandNameColumnWidthMax < $subcommandNameColumnWidth) {
                 $subcommandNameColumnWidthMax = $subcommandNameColumnWidth;
             }
@@ -223,7 +228,8 @@ protected function outputNode(
                 echo PHP_EOL;
             }
 
-            $subcommandNameOutput = str_repeat(static::PADDING_BLOCK, $nodeLevel) . $elementName;
+            $subcommandNameOutput = str_repeat(' ', $this->paddingLeftMain + $this->paddingLeftCommand * $nodeLevel)
+                . $elementName;
             if ($elementValue instanceof Config) {
                 $subcommandNameOutputFormatted = $subcommandNameOutput;
                 if ('' !== $this->subcommandNamePart) {
@@ -235,18 +241,19 @@ protected function outputNode(
                 }
                 echo $this->formatter->paramValue($subcommandNameOutputFormatted);
             } else {
-                if (0 === $nodeLevel) {
-                    echo ' ';
-                }
                 echo $this->formatter->helpNote($subcommandNameOutput);
             }
 
             if ($elementValue instanceof Config) {
                 $shortDescription = HelpGenerator::getScriptShortDescription($elementValue, $this->environmentConfig);
 
                 if ('' !== $shortDescription) {
-                    echo mb_str_pad('', $subcommandNameColumnWidthMax - mb_strlen($subcommandNameOutput))
-                        . static::PADDING_BLOCK . $shortDescription;
+                    echo str_repeat(
+                            ' ',
+                            $this->paddingLeftMain + $this->paddingLeftCommandDescription
+                                + $subcommandNameColumnWidthMax - mb_strlen($subcommandNameOutput),
+                        )
+                        . $shortDescription;
                 }
             }
             echo PHP_EOL;