Merge branch 'add-cli-methods'

lkrms · lkrms · commit a8ec24563e3f · 2024-01-20T15:21:35.000+11:00
diff --git a/src/Cli/CliApplication.php b/src/Cli/CliApplication.php
@@ -28,20 +28,18 @@
  */
 class CliApplication extends Application implements ICliApplication
 {
+    private const COMMAND_REGEX = '/^[a-z][a-z0-9_-]*$/iD';
+
     /**
      * @var array<string,class-string<CliCommand>|mixed[]>
      */
     private $CommandTree = [];
 
-    /**
-     * @var CliCommand|null
-     */
-    private $RunningCommand;
+    private ?CliCommand $RunningCommand = null;
 
-    /**
-     * @var int
-     */
-    private $LastExitStatus = 0;
+    private ?CliCommand $LastCommand = null;
+
+    private int $LastExitStatus = 0;
 
     public function __construct(
         ?string $basePath = null,
@@ -73,6 +71,14 @@ public function getRunningCommand(): ?CliCommand
         return $this->RunningCommand;
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function getLastCommand(): ?CliCommand
+    {
+        return $this->LastCommand;
+    }
+
     /**
      * @inheritDoc
      */
@@ -141,51 +147,25 @@ protected function getNode(array $name = [])
     }
 
     /**
-     * Register one, and only one, CliCommand for the lifetime of the container
-     *
-     * The command is registered with an empty name, placing it at the root of
-     * the container's subcommand tree.
-     *
-     * @param class-string<CliCommand> $id The name of the class to instantiate.
-     * @return $this
-     * @throws LogicException if another command has already been registered.
+     * @inheritDoc
      */
     public function oneCommand(string $id)
     {
         return $this->command([], $id);
     }
 
     /**
-     * Register a CliCommand with the container
-     *
-     * For example, an executable PHP script called `sync-util` could register
-     * `Acme\Canvas\Sync`, a {@see CliCommand} inheritor, as follows:
-     *
-     * ```php
-     * (new CliApplication())
-     *     ->command(['sync', 'canvas'], \Acme\Canvas\Sync::class)
-     *     ->runAndExit();
-     * ```
-     *
-     * Then, `Acme\Canvas\Sync` could be invoked with:
-     *
-     * ```shell
-     * ./sync-util sync canvas
-     * ```
-     *
-     * @param string[] $name The name of the command as an array of subcommands.
-     *
-     * Valid subcommands start with a letter, followed by any number of letters,
-     * numbers, hyphens and underscores.
-     * @param class-string<CliCommand> $id The name of the class to instantiate.
-     * @return $this
-     * @throws LogicException if `$name` is invalid or conflicts with a
-     * registered command.
+     * @inheritDoc
      */
     public function command(array $name, string $id)
     {
-        foreach ($name as $i => $subcommand) {
-            Assert::isMatch($subcommand, '/^[a-zA-Z][a-zA-Z0-9_-]*$/', "\$name[$i]");
+        foreach ($name as $subcommand) {
+            if (!Pcre::match(self::COMMAND_REGEX, $subcommand)) {
+                throw new LogicException(sprintf(
+                    'Subcommand does not start with a letter, followed by zero or more letters, numbers, hyphens or underscores: %s',
+                    $subcommand,
+                ));
+            }
         }
 
         if ($this->getNode($name) !== null) {
@@ -419,6 +399,9 @@ public function run()
             return $this;
         } finally {
             $this->RunningCommand = null;
+            if ($command !== null) {
+                $this->LastCommand = $command;
+            }
         }
     }
 
diff --git a/src/Cli/CliCommand.php b/src/Cli/CliCommand.php
@@ -889,6 +889,16 @@ final protected function getOptionValue(string $name)
         return $this->OptionValues[$option->Key] ?? null;
     }
 
+    /**
+     * True if an option was given on the command line
+     */
+    final protected function optionHasArgument(string $name): bool
+    {
+        $this->assertHasRun()->loadOptions();
+        $option = $this->_getOption($name, false);
+        return array_key_exists($option->Key, $this->ArgumentValues);
+    }
+
     /**
      * Get the given option
      */
@@ -1150,6 +1160,8 @@ private function optionError(string $message): void
     }
 
     /**
+     * Get the command's options
+     *
      * @return list<CliOption>
      */
     final protected function getOptions(): array
@@ -1321,7 +1333,7 @@ final protected function getExitStatus(): int
      * Get the number of times the command has run, including the current run
      * (if applicable)
      */
-    final protected function getRuns(): int
+    final public function getRuns(): int
     {
         return $this->Runs;
     }
diff --git a/src/Cli/Contract/ICliApplication.php b/src/Cli/Contract/ICliApplication.php
@@ -11,65 +11,73 @@
 interface ICliApplication extends IApplication
 {
     /**
-     * Get the command started from the command line
+     * Get the command invoked by run()
+     *
+     * This method should only return a command that is currently running.
      */
     public function getRunningCommand(): ?ICliCommand;
 
+    /**
+     * Get the command most recently invoked by run()
+     *
+     * This method should only return a command that ran to completion or failed
+     * with an exception.
+     */
+    public function getLastCommand(): ?ICliCommand;
+
     /**
      * Get the return value most recently recorded by run()
      *
-     * Returns `0` if {@see ICliApplication::run()} has not recorded a return
-     * value.
+     * This method should return `0` if a return value has not been recorded.
      */
     public function getLastExitStatus(): int;
 
     /**
      * Register a command with the container
      *
      * @param string[] $name The name of the command as an array of subcommands.
-     *
      * Valid subcommands start with a letter, followed by any number of letters,
      * numbers, hyphens and underscores.
-     * @param class-string<ICliCommand> $id The name of the class to register.
+     * @param class-string<ICliCommand> $id
      * @return $this
      * @throws LogicException if `$name` is invalid or conflicts with a
      * registered command.
      */
     public function command(array $name, string $id);
 
     /**
-     * Register one, and only one, ICliCommand for the lifetime of the container
+     * Register one, and only one, command for the lifetime of the container
      *
-     * The command is registered with an empty name, placing it at the root of
-     * the container's subcommand tree.
+     * Calling this method should have the same effect as calling
+     * {@see ICliApplication::command()} with an empty command name.
      *
-     * @param class-string<ICliCommand> $id The name of the class to register.
+     * @param class-string<ICliCommand> $id
      * @return $this
      * @throws LogicException if another command has already been registered.
-     *
-     * @see ICliApplication::command()
      */
     public function oneCommand(string $id);
 
     /**
      * Process command line arguments passed to the script and record a return
      * value
      *
-     * The first applicable action is taken:
+     * This method should take the first applicable action:
      *
      * - If `--help` is the only remaining argument after processing subcommand
-     *   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 the return value is `0`.
-     * - If subcommand arguments resolve to a registered command, it is invoked
-     *   and the return value is its exit status.
+     *   arguments, print a help message to `STDOUT`. Return value: `0`
+     *
+     * - If `--version` is the only remaining argument, print the application's
+     *   name and version number to `STDOUT`. Return value: `0`
+     *
+     * - If subcommand arguments resolve to a registered command, create an
+     *   instance of the command and run it. Return value: command 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 the return value is `0`.
+     *   arguments but there are further subcommands, print a one-line synopsis
+     *   of each registered subcommand. Return value: `0`
      *
-     * Otherwise, an error is reported, a one-line synopsis of each registered
-     * subcommand is printed, and the return value is `1`.
+     * - Report an error and print a one-line synopsis of each registered
+     *   subcommand. Return value: `1`
      *
      * @return $this
      */
@@ -78,18 +86,18 @@ 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.
+     * This method should use exit status `0` if a return value has not been
+     * recorded.
      *
      * @return never
      */
     public function exit();
 
     /**
-     * Exit after processing command line arguments passed to the script
+     * Process command line arguments passed to the script and exit with the
+     * recorded return value
      *
-     * The return value recorded by {@see ICliApplication::run()} is used as the
-     * exit status.
+     * See {@see ICliApplication::run()} for details.
      *
      * @return never
      */
diff --git a/src/Utility/Assert.php b/src/Utility/Assert.php
@@ -158,29 +158,6 @@ public static function isString(
         self::throw('{} must be a string', $name, $exception);
     }
 
-    /**
-     * Assert that a value is a string that matches a regular expression
-     *
-     * @template TException of Throwable
-     *
-     * @param mixed $value
-     * @param class-string<TException> $exception
-     * @throws TException if `$value` is not a string or does not match
-     * `$pattern`.
-     * @phpstan-assert string $value
-     */
-    public static function isMatch(
-        $value,
-        string $pattern,
-        ?string $name = null,
-        string $exception = AssertionFailedException::class
-    ): void {
-        if (is_string($value) && Pcre::match($pattern, $value)) {
-            return;
-        }
-        self::throw(sprintf('{} must match regular expression: %s', $pattern), $name, $exception);
-    }
-
     /**
      * Assert that PHP is running on the command line
      *
diff --git a/tests/fixtures/Cli/Command/TestOptions.php b/tests/fixtures/Cli/Command/TestOptions.php
@@ -6,7 +6,6 @@
 use Lkrms\Cli\Catalog\CliOptionValueType;
 use Lkrms\Cli\CliCommand;
 use Lkrms\Cli\CliOption;
-use Lkrms\Support\Date\DateFormatter;
 use Lkrms\Utility\Json;
 use DateTimeInterface;
 
@@ -104,7 +103,11 @@ protected function getOptionList(): array
 
     protected function run(string ...$args)
     {
-        $dateFormatter = new DateFormatter();
+        foreach ($this->getOptions() as $option) {
+            if ($this->optionHasArgument($option->Name)) {
+                $hasArg[$option->Name] = true;
+            }
+        }
 
         echo Json::prettyPrint([
             'args' => $args,
@@ -117,6 +120,7 @@ protected function run(string ...$args)
                 'RepeatableValue' => $this->RepeatableValue,
                 'RequiredValue' => $this->RequiredValue,
             ],
+            'hasArg' => $hasArg ?? [],
         ]) . \PHP_EOL;
     }
 }
diff --git a/tests/unit/Cli/CliApplicationTest.php b/tests/unit/Cli/CliApplicationTest.php
@@ -129,12 +129,25 @@ public function testCommandOptionValues(): void
                         "timezone_type": 1,
                         "timezone": "+11:00"
                     }
+                },
+                "hasArg": {
+                    "start": true
                 }
             }
 
             EOF);
         $app = $this->App->oneCommand(TestOptions::class);
         $this->assertSame(0, $app->run()->getLastExitStatus());
+        $this->assertInstanceOf(TestOptions::class, $command = $app->getLastCommand());
+        $this->assertSame(1, $command->getRuns());
+    }
+
+    public function testInvalidSubcommand(): void
+    {
+        $this->expectException(LogicException::class);
+        $this->expectExceptionMessage('Subcommand does not start with a letter, followed by zero or more letters, numbers, hyphens or underscores: _options');
+
+        $this->App->command(['_options', 'test'], TestOptions::class);
     }
 
     public function testCommandCollision(): void
diff --git a/tests/unit/Utility/AssertTest.php b/tests/unit/Utility/AssertTest.php
@@ -279,41 +279,6 @@ public static function isStringProvider(): array
         ];
     }
 
-    /**
-     * @dataProvider isMatchProvider
-     *
-     * @param mixed $value
-     */
-    public function testIsMatch(bool $isMatch, $value, string $pattern, ?string $name = null, ?string $message = null): void
-    {
-        if ($isMatch) {
-            $this->expectNotToPerformAssertions();
-        } else {
-            $this->expectException(AssertionFailedException::class);
-            if ($message !== null) {
-                $this->expectExceptionMessage($message);
-            }
-        }
-        Assert::isMatch($value, $pattern, $name);
-    }
-
-    /**
-     * @return array<array{bool,mixed,string,3?:string|null,4?:string|null}>
-     */
-    public static function isMatchProvider(): array
-    {
-        return [
-            [true, '', '/.*/'],
-            [true, 'Text', '/^t.+t$/i'],
-            [false, '', '/.+/'],
-            [false, null, '/.+/', '$arg', '$arg must match regular expression: /.+/'],
-            [false, 0, '/.*/', null, 'value must match regular expression: /.*/'],
-            [false, 1, '/.*/'],
-            [false, false, '/.*/'],
-            [false, true, '/.*/'],
-        ];
-    }
-
     public function testRunningOnCli(): void
     {
         if (\PHP_SAPI === 'cli') {

Original file line number	Diff line number	Diff line change
`@@ -129,12 +129,25 @@ public function testCommandOptionValues(): void`
`129`	`129`	`"timezone_type": 1,`
`130`	`130`	`"timezone": "+11:00"`
`131`	`131`	`}`
	`132`	`+ },`
	`133`	`+ "hasArg": {`
	`134`	`+ "start": true`
`132`	`135`	`}`
`133`	`136`	`}`
`134`	`137`
`135`	`138`	`EOF);`
`136`	`139`	`$app = $this->App->oneCommand(TestOptions::class);`
`137`	`140`	`$this->assertSame(0, $app->run()->getLastExitStatus());`
	`141`	`+ $this->assertInstanceOf(TestOptions::class, $command = $app->getLastCommand());`
	`142`	`+ $this->assertSame(1, $command->getRuns());`
	`143`	`+ }`
	`144`	`+`
	`145`	`+ public function testInvalidSubcommand(): void`
	`146`	`+ {`
	`147`	`+ $this->expectException(LogicException::class);`
	`148`	`+ $this->expectExceptionMessage('Subcommand does not start with a letter, followed by zero or more letters, numbers, hyphens or underscores: _options');`
	`149`	`+`
	`150`	`+ $this->App->command(['_options', 'test'], TestOptions::class);`
`138`	`151`	`}`
`139`	`152`
`140`	`153`	`public function testCommandCollision(): void`