Show all subcommands in usages from the top to a current branch.

Author: MagicPush

docs/changelog.md

@@ -13,8 +13,11 @@ This change log references the repository changes and releases, which respect [s
    in your production classes under 'dev' environment (when you call `composer install` without `--no-dev` option),
    you will get "Class 'XXX' not found in ..." error.
    Previously there was no error, until you install composer packages with `--no-dev` flag.
-1. Fixed scripts main description block - stopped counting symbols in space-only lines.
-   Previously it caused too much padding for descriptions with too short space-only lines.
+1. `HelpGenerator`:
+    1. Fixed scripts main description block - stopped counting symbols in space-only lines.
+       Previously it caused too much padding for descriptions with too short space-only lines.
+    1. Improved subcommand help usage block - when `--help` is called for a subcommand, all manual usage lines
+       include the whole path (subcommand values) starting from the topmost config.
 
 ## v2.0.0
 

docs/todo.md

@@ -158,6 +158,7 @@ The list of plans and ideas for future development.
 Let's try making major releases less frequent by accumulating here all ideas with backward incompatibilities.
 When the time comes, the whole bunch of stuff mentioned here will be implemented in a single major version.
 
+1. Remove now obsolete `HelpGenerator::getBaseScriptName()`.
 1. Move to PHP 8.4 as a minimal required version. This includes:
     1. Replace `*trim()` functions with `mb_*trim()` alternatives.
 

src/Parametizer/Config/HelpGenerator.php

@@ -166,8 +166,14 @@ public function getUsagesBlock(): string {
         // Print general usage template:
         $output .= $this->getUsageTemplate($this->config);
 
-        $usageExamples  = $this->config->getUsageExamples();
-        $baseScriptName = static::getBaseScriptName($this->config);
+        $branchConfig    = $this->config;
+        $scriptNameParts = [];
+        do {
+            $scriptNameParts[] = $branchConfig->getScriptName();
+        } while ($branchConfig = $branchConfig->getParent());
+        $baseScriptName = implode(' ', array_reverse($scriptNameParts));
+
+        $usageExamples = $this->config->getUsageExamples();
 
         // Firstly print usage examples with no description:
         foreach ($usageExamples as $usageExample) {

tests/Tests/Parametizer/HelpGenerator/HelpGeneratorTest.php

@@ -105,6 +105,9 @@ public function testSubcommandScriptHelpFirstLevel(): void {
 
           deep-nesting.php <switchme>
 
+          Very deep call:
+          deep-nesting.php test11 --name-l2=supername test23 --name-l3=nameLevelThree test32
+
         OPTIONS
 
           --help   Show full help page.
@@ -130,7 +133,7 @@ public function testSubcommandScriptHelpFirstLevel(): void {
      * Help for a specific subcommand.
      *
      * @see HelpGenerator::getFullHelp()
-     * @see HelpGenerator::getBaseScriptName()
+     * @see HelpGenerator::getUsagesBlock()
      */
     public function testSubcommandScriptHelpDeepInSubcommand(): void {
         assertSame(
@@ -139,10 +142,10 @@ public function testSubcommandScriptHelpDeepInSubcommand(): void {
         USAGE
 
           deep-nesting.php test11 [--name-l2=…] test23 [--name-l3=…] <switchme-l3>
-          deep-nesting.php test11 --name-l2=supername test23 test31
+          deep-nesting.php test11 test23 test31
 
           Very deep call:
-          deep-nesting.php test11 --name-l2=supername test23 --name-l3=nameLevelThree test32
+          deep-nesting.php test11 test23 --name-l3=nameLevelThree test32
 
         OPTIONS
 

tests/Tests/Parametizer/HelpGenerator/scripts/deep-nesting.php

@@ -7,6 +7,13 @@
 require_once __DIR__ . '/../../../init-console.php';
 
 Parametizer::newConfig(throwOnException: true)
+    // When you observe the whole config tree looking from the perspective of the very parent,
+    // you may manually specify a deep subcommand usage example...
+    ->usage(
+        'test11 --name-l2=supername test23 --name-l3=nameLevelThree test32',
+        'Very deep call',
+    )
+
     ->newSubcommandSwitch('switchme')
     ->newSubcommand(
         'test11',
@@ -17,9 +24,15 @@
             ->newSubcommand(
                 'test23',
                 Parametizer::newConfig(throwOnException: true)
-                    ->usage('test11 --name-l2=supername test23 test31')
+                    /*
+                     * ... However when looking from the perspective of a branch, you should not be aware of parent
+                     * configs - think of branches as configs included automatically during runtime.
+                     * The point is that the help generator should detect correct paths up to the very top
+                     * and reflect it in the subcommand help usage block.
+                     */
+                    ->usage('test31')
                     ->usage(
-                        'test11 --name-l2=supername test23 --name-l3=nameLevelThree test32',
+                        '--name-l3=nameLevelThree test32',
                         'Very deep call',
                     )