Merge branch 'cli-documentation'

Author: lkrms

src/Cli/Catalog/CliOptionVisibility.php

@@ -5,23 +5,46 @@
 use Lkrms\Concept\Enumeration;
 
 /**
- * Command line option display locations
+ * Command line option visibility flags
  *
  * @extends Enumeration<int>
  */
 final class CliOptionVisibility extends Enumeration
 {
+    /**
+     * Don't include the option in any help output
+     */
     public const NONE = 0;
 
+    /**
+     * Include the option in command synopses
+     */
     public const SYNOPSIS = 1;
 
+    /**
+     * Include the option when writing help to a terminal
+     */
     public const HELP = 2;
 
+    /**
+     * Include the option when writing help as Markdown
+     */
     public const MARKDOWN = 4;
 
+    /**
+     * Include the option when writing help as Markdown with man page extensions
+     */
     public const MAN_PAGE = 8;
 
+    /**
+     * Include the option when generating shell completions
+     */
     public const COMPLETION = 16;
 
+    /**
+     * Hide the option's default value if not writing help to a terminal
+     */
+    public const HIDE_DEFAULT = 32;
+
     public const ALL = CliOptionVisibility::SYNOPSIS | CliOptionVisibility::HELP | CliOptionVisibility::MARKDOWN | CliOptionVisibility::MAN_PAGE | CliOptionVisibility::COMPLETION;
 }

src/Cli/CliApplication.php

@@ -6,6 +6,7 @@
 use Lkrms\Cli\Catalog\CliHelpType;
 use Lkrms\Cli\Contract\ICliApplication;
 use Lkrms\Cli\Exception\CliInvalidArgumentsException;
+use Lkrms\Cli\Support\CliHelpStyle;
 use Lkrms\Cli\CliCommand;
 use Lkrms\Console\Support\ConsoleTagFormats as TagFormats;
 use Lkrms\Console\ConsoleFormatter as Formatter;
@@ -39,6 +40,11 @@ class CliApplication extends Application implements ICliApplication
      */
     private $HelpType = CliHelpType::TTY;
 
+    /**
+     * @var CliHelpStyle|null
+     */
+    private $HelpStyle;
+
     public function __construct(string $basePath = null)
     {
         parent::__construct($basePath);
@@ -203,13 +209,16 @@ public function command(array $name, string $id)
     private function getUsage(string $name, $node, bool $terse = false): ?string
     {
         $width = $this->getHelpWidth($terse);
+
+        $command = $this->getNodeCommand($name, $node);
+        if ($command && !$terse) {
+            return $this->buildHelp($command->getHelp(true, $width));
+        }
+
         $progName = $this->getProgramName();
         $fullName = trim("$progName $name");
 
-        if ($command = $this->getNodeCommand($name, $node)) {
-            if (!$terse) {
-                return $command->getHelp(true, $width);
-            }
+        if ($command) {
             return Formatter::escapeTags($command->getSynopsis(false, $width)
                 . "\n\nSee '"
                 . ($name ? "$progName help $name" : "$progName --help")
@@ -261,6 +270,15 @@ public function getHelpType(): int
         return $this->HelpType;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getHelpStyle(): CliHelpStyle
+    {
+        return $this->HelpStyle
+            ?? ($this->HelpStyle = new CliHelpStyle($this->HelpType));
+    }
+
     /**
      * @inheritDoc
      */
@@ -425,13 +443,14 @@ public function runAndExit()
 
     /**
      * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand> $node
-     * @param CliHelpType::* $type
+     * @param CliHelpType::* $helpType
      */
-    private function generateHelp(string $name, $node, int $type, string ...$args): int
+    private function generateHelp(string $name, $node, int $helpType, string ...$args): int
     {
-        $this->HelpType = $type;
+        $this->HelpType = $helpType;
+        $this->HelpStyle = null;
 
-        switch ($type) {
+        switch ($helpType) {
             case CliHelpType::MARKDOWN:
                 $formats = TagFormats::getMarkdownFormats();
                 break;
@@ -442,13 +461,13 @@ private function generateHelp(string $name, $node, int $type, string ...$args):
                     "%% %s(%d) %s | %s\n\n",
                     strtoupper(str_replace(' ', '-', trim($this->getProgramName() . " $name"))),
                     (int) ($args[0] ?? '1'),
-                    $args[1] ?? Composer::getRootPackageVersion(true, true),
+                    $args[1] ?? Composer::getRootPackageVersion(true),
                     $args[2] ?? (Composer::getRootPackageName() . ' Documentation'),
                 );
                 break;
 
             default:
-                throw new LogicException(sprintf('Invalid help type: %d', $type));
+                throw new LogicException(sprintf('Invalid help type: %d', $helpType));
         }
 
         $formatter = new Formatter($formats);