Merge branch 'improve-cli-chaining'

lkrms · lkrms · commit e87614ac8ffa · 2023-10-31T16:15:37.000+11:00
diff --git a/src/Cli/CliApplication.php b/src/Cli/CliApplication.php
@@ -36,7 +36,7 @@ class CliApplication extends Application implements ICliApplication
     private $RunningCommand;
 
     /**
-     * @var CliHelpType::*
+     * @var int&CliHelpType::*
      */
     private $HelpType = CliHelpType::TTY;
 
@@ -45,6 +45,11 @@ class CliApplication extends Application implements ICliApplication
      */
     private $HelpStyle;
 
+    /**
+     * @var int
+     */
+    private $LastExitStatus = 0;
+
     public function __construct(
         ?string $basePath = null,
         ?string $appName = null,
@@ -67,11 +72,22 @@ public function __construct(
         Sys::handleExitSignals();
     }
 
+    /**
+     * @inheritDoc
+     */
     public function getRunningCommand(): ?CliCommand
     {
         return $this->RunningCommand;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getLastExitStatus(): int
+    {
+        return $this->LastExitStatus;
+    }
+
     /**
      * Get a CliCommand instance from the given node in the command tree
      *
@@ -336,8 +352,10 @@ public function buildHelp(array $sections): string
     /**
      * @inheritDoc
      */
-    public function run(): int
+    public function run()
     {
+        $this->LastExitStatus = 0;
+
         $args = array_slice($_SERVER['argv'], 1);
 
         $lastNode = null;
@@ -352,15 +370,15 @@ public function run(): int
             if ($arg === '--help' && !$args) {
                 $usage = $this->getUsage($name, $node);
                 Console::stdout($usage);
-                return 0;
+                return $this;
             }
 
             // or version number if it's "--version"
             if ($arg === '--version' && !$args) {
                 $appName = $this->getAppName();
                 $version = Composer::getRootPackageVersion(true, true);
                 Console::stdout("__{$appName}__ $version");
-                return 0;
+                return $this;
             }
 
             // - If $args was empty before this iteration, print terse usage
@@ -371,9 +389,11 @@ public function run(): int
                     !preg_match('/^[a-zA-Z][a-zA-Z0-9_-]*$/', $arg)) {
                 $usage = $this->getUsage($name, $node, true);
                 Console::out($usage);
-                return $arg === null
-                    ? 0
-                    : 1;
+                $this->LastExitStatus =
+                    $arg === null
+                        ? 0
+                        : 1;
+                return $this;
             }
 
             // Descend into the command tree if $arg is a registered subcommand
@@ -406,12 +426,14 @@ public function run(): int
 
         if (($args[0] ?? null) === '_md') {
             array_shift($args);
-            return $this->generateHelp($name, $node, CliHelpType::MARKDOWN, ...$args);
+            $this->generateHelp($name, $node, CliHelpType::MARKDOWN, ...$args);
+            return $this;
         }
 
         if (($args[0] ?? null) === '_man') {
             array_shift($args);
-            return $this->generateHelp($name, $node, CliHelpType::MAN_PAGE, ...$args);
+            $this->generateHelp($name, $node, CliHelpType::MAN_PAGE, ...$args);
+            return $this;
         }
 
         $command = $this->getNodeCommand($name, $node);
@@ -422,7 +444,8 @@ public function run(): int
                 );
             }
             $this->RunningCommand = $command;
-            return $command(...$args);
+            $this->LastExitStatus = $command(...$args);
+            return $this;
         } catch (CliInvalidArgumentsException $ex) {
             $ex->reportErrors();
             if (!$node) {
@@ -433,22 +456,34 @@ public function run(): int
                     ($usage = $this->getUsage($name, $node, true)) !== null) {
                 Console::out("\n{$usage}");
             }
-            return 1;
+            $this->LastExitStatus = 1;
+            return $this;
         } finally {
             $this->RunningCommand = null;
         }
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function exit()
+    {
+        exit ($this->LastExitStatus);
+    }
+
+    /**
+     * @inheritDoc
+     */
     public function runAndExit()
     {
-        exit ($this->run());
+        $this->run()->exit();
     }
 
     /**
      * @param array<string,class-string<CliCommand>|mixed[]>|class-string<CliCommand> $node
      * @param CliHelpType::* $helpType
      */
-    private function generateHelp(string $name, $node, int $helpType, string ...$args): int
+    private function generateHelp(string $name, $node, int $helpType, string ...$args): void
     {
         $this->HelpType = $helpType;
         $this->HelpStyle = null;
@@ -477,7 +512,5 @@ private function generateHelp(string $name, $node, int $helpType, string ...$arg
         $usage = $this->getUsage($name, $node);
         $usage = $formatter->formatTags($usage, false, null, false);
         printf("%s\n", str_replace('\ ', ' ', $usage));
-
-        return 0;
     }
 }
diff --git a/src/Cli/CliCommand.php b/src/Cli/CliCommand.php
@@ -241,15 +241,15 @@ private function addOption(CliOption $option)
         try {
             $option->validate();
         } catch (CliUnknownValueException $ex) {
-            $this->deferOptionError($ex->getMessage());
+            // If an exception is thrown over a value found in the environment,
+            // defer it because we may only be loading options to generate a
+            // synopsis
+            $this->DeferredOptionErrors[] = $ex->getMessage();
         }
 
         $names = $option->getNames();
 
-        if (array_intersect_key(
-            array_flip($names),
-            $this->OptionsByName
-        )) {
+        if (array_intersect_key(array_flip($names), $this->OptionsByName)) {
             throw new LogicException('Option names must be unique: ' . implode(', ', $names));
         }
 
@@ -262,6 +262,7 @@ private function addOption(CliOption $option)
                     )) {
                 throw new LogicException('Required positional options must be added before optional ones');
             }
+
             if (!$option->Required &&
                     array_filter(
                         $this->PositionalOptions,
@@ -270,6 +271,7 @@ private function addOption(CliOption $option)
                     )) {
                 throw new LogicException("'multipleAllowed' positional options must be added after optional ones");
             }
+
             if ($option->MultipleAllowed &&
                     array_filter(
                         $this->PositionalOptions,
@@ -690,34 +692,8 @@ private function optionError(string $message)
         return $this;
     }
 
-    /**
-     * Record an option-related error to report only if the command is running
-     *
-     * @return $this
-     * @phpstan-impure
-     */
-    private function deferOptionError(string $message)
-    {
-        $this->DeferredOptionErrors[] = $message;
-
-        return $this;
-    }
-
-    /**
-     * @return $this
-     */
-    private function loadOptionValues()
+    private function loadOptionValues(): void
     {
-        if ($this->OptionValues !== null) {
-            return $this;
-        }
-
-        $this->ArgumentValues = [];
-        $this->OptionErrors = [];
-        $this->NextArgumentIndex = null;
-        $this->HasHelpArgument = false;
-        $this->HasVersionArgument = false;
-
         $this->loadOptions();
 
         try {
@@ -764,8 +740,6 @@ private function loadOptionValues()
                     ...$this->DeferredOptionErrors
                 );
             }
-
-            return $this;
         } catch (Throwable $ex) {
             $this->OptionValues = null;
 
@@ -1225,9 +1199,9 @@ private function assertHasRun()
      */
     final public function __invoke(string ...$args): int
     {
+        $this->reset();
+
         $this->Arguments = $args;
-        $this->OptionValues = null;
-        $this->ExitStatus = 0;
         $this->Runs++;
 
         $this->loadOptionValues();
@@ -1308,6 +1282,18 @@ final protected function getRuns(): int
         return $this->Runs;
     }
 
+    private function reset(): void
+    {
+        $this->Arguments = [];
+        $this->ArgumentValues = [];
+        $this->OptionValues = null;
+        $this->OptionErrors = [];
+        $this->NextArgumentIndex = null;
+        $this->HasHelpArgument = false;
+        $this->HasVersionArgument = false;
+        $this->ExitStatus = 0;
+    }
+
     private function getLoopbackFormatter(): Formatter
     {
         return $this->LoopbackFormatter
diff --git a/src/Cli/Contract/ICliApplication.php b/src/Cli/Contract/ICliApplication.php
@@ -18,6 +18,14 @@ interface ICliApplication extends IApplication
      */
     public function getRunningCommand(): ?ICliCommand;
 
+    /**
+     * Get the return value most recently recorded by run()
+     *
+     * Returns `0` if {@see ICliApplication::run()} has not recorded a return
+     * value.
+     */
+    public function getLastExitStatus(): int;
+
     /**
      * Register a command with the container
      *
@@ -84,30 +92,44 @@ public function getHelpWidth(bool $terse = false): ?int;
     public function buildHelp(array $sections): string;
 
     /**
-     * Process command-line arguments passed to the script
+     * Process command-line arguments passed to the script and record a return
+     * value
      *
      * The first applicable action is taken:
      *
      * - If `--help` is the only remaining argument after processing subcommand
-     *   arguments, a help message is printed to `STDOUT` and `0` is returned.
+     *   arguments, a help message is printed to `STDOUT` and the return value
+     *   is `0`.
      * - If `--version` is the only remaining argument, the application's name
-     *   and version number is printed to `STDOUT` and `0` is returned.
+     *   and version number is printed to `STDOUT` and the return value is `0`.
      * - If subcommand arguments resolve to a registered command, it is invoked
-     *   and its exit status is returned.
+     *   and the return value is its exit status.
      * - If, after processing subcommand arguments, there are no further
      *   arguments but there are further subcommands, a one-line synopsis of
-     *   each registered subcommand is printed and `0` is returned.
+     *   each registered subcommand is printed and the return value is `0`.
      *
      * Otherwise, an error is reported, a one-line synopsis of each registered
-     * subcommand is printed, and `1` is returned.
+     * subcommand is printed, and the return value is `1`.
+     *
+     * @return $this
+     */
+    public function run();
+
+    /**
+     * Exit with the return value most recently recorded by run()
+     *
+     * The exit status is `0` if {@see ICliApplication::run()} has not recorded
+     * a return value.
+     *
+     * @return never
      */
-    public function run(): int;
+    public function exit();
 
     /**
      * Exit after processing command-line arguments passed to the script
      *
-     * The value returned by {@see ICliApplication::run()} is used as the exit
-     * status.
+     * The return value recorded by {@see ICliApplication::run()} is used as the
+     * exit status.
      *
      * @return never
      */
