diff --git a/README.md b/README.md index a59086c..416627a 100644 --- a/README.md +++ b/README.md @@ -170,11 +170,15 @@ class InitCommand extends Ahc\Cli\Input\Command { parent::__construct('init', 'Init something'); + $help = 'Custom help screen'; + $writer = new Ahc\Cli\Output\Writer(); + $this ->argument('', 'The Arrg') ->argument('[arg2]', 'The Arg2') ->option('-a --apple', 'The Apple') ->option('-b --ball', 'The ball') + ->help($writer->colorizer()->colors($help)) // Usage examples: ->usage( // append details or explanation of given example with ` ## ` so they will be uniformly aligned when shown @@ -243,6 +247,9 @@ $app->add(new OtherCommand, 'o'); // Set logo $app->logo('Ascii art logo of your app'); +// Custom help screen +$app->help('Custom help screen (if omitted one will be generated)'); + $app->handle($_SERVER['argv']); // if argv[1] is `i` or `init` it executes InitCommand ``` diff --git a/src/Application.php b/src/Application.php index eb5d5e1..187089c 100644 --- a/src/Application.php +++ b/src/Application.php @@ -52,6 +52,10 @@ class Application /** @var string Ascii art logo */ protected string $logo = ''; + /** @var string Custom help screen */ + protected string $help = ''; + + /** @var string Name of default command */ protected string $default = '__default__'; /** @var null|Interactor */ @@ -344,9 +348,42 @@ protected function aliasesFor(Command $command): array } /** - * Show help of all commands. + * Sets or gets the custom help screen contents. + * + * @param string|null $help + * + * @return string|self + */ + public function help(?string $help = null): mixed + { + if (func_num_args() === 0) { + return $this->help; + } + + $this->help = $help; + + return $this; + } + + /** + * Show custom help screen if one is set, otherwise shows the default one. */ public function showHelp(): mixed + { + if ($help = $this->help()) { + $writer = $this->io()->writer(); + $writer->write($help, true); + + return ($this->onExit)(); + } + + return $this->showDefaultHelp(); + } + + /** + * Shows command help then aborts. + */ + public function showDefaultHelp(): mixed { $writer = $this->io()->writer(); $header = "{$this->name}, version {$this->version}"; diff --git a/src/Input/Command.php b/src/Input/Command.php index 49dbfb4..c1fc9f2 100644 --- a/src/Input/Command.php +++ b/src/Input/Command.php @@ -52,6 +52,8 @@ class Command extends Parser implements Groupable protected ?string $_alias = null; + protected string $_help = ''; + private array $_events = []; private bool $_argVariadic = false; @@ -291,9 +293,42 @@ protected function handleUnknown(string $arg, ?string $value = null): mixed } /** - * Shows command help then aborts. + * Sets or gets the custom help screen contents. + * + * @param string|null $help + * + * @return string|self + */ + public function help(?string $help = null): mixed + { + if (func_num_args() === 0) { + return $this->_help; + } + + $this->_help = $help; + + return $this; + } + + /** + * Show custom help screen if one is set, otherwise shows the default one. */ public function showHelp(): mixed + { + if ($help = $this->help()) { + $writer = $this->io()->writer(); + $writer->write($help, true); + + return $this->emit('_exit', 0); + } + + return $this->showDefaultHelp(); + } + + /** + * Shows command help then aborts. + */ + public function showDefaultHelp(): mixed { $io = $this->io(); $helper = new OutputHelper($io->writer()); diff --git a/tests/ApplicationTest.php b/tests/ApplicationTest.php index b6fce4f..de4cbb5 100644 --- a/tests/ApplicationTest.php +++ b/tests/ApplicationTest.php @@ -147,6 +147,17 @@ public function test_help() $this->assertStringContainsString('stage change', $out); } + public function testCustomHelp() + { + $this->newApp('git', '0.0.2') + ->help('This should be my custom help screen') + ->parse(['git', '--help']); + + $out = file_get_contents(static::$ou); + + $this->assertStringContainsString('This should be my custom help screen', $out); + } + public function test_action() { ($a = $this->newApp('git', '0.0.2')) diff --git a/tests/Input/CommandTest.php b/tests/Input/CommandTest.php index 4c03622..4cb5754 100644 --- a/tests/Input/CommandTest.php +++ b/tests/Input/CommandTest.php @@ -285,6 +285,13 @@ public function __construct($tester) }; } + public function test_custom_help() + { + $p = $this->newCommand(); + $p->help('This should be my custom help screen'); + $this->assertStringContainsString('This should be my custom help screen', $p->help()); + } + protected function newCommand(string $version = '0.0.1', string $desc = '', bool $allowUnknown = false, $app = null) { $p = new Command('cmd', $desc, $allowUnknown, $app);