Add support for outputting 256 colors and also add documentation about default command functionality

README.md

@@ -170,11 +170,15 @@ class InitCommand extends Ahc\Cli\Input\Command
     {
         parent::__construct('init', 'Init something');
 
+        $help = '<cyan>Custom help screen</end>';
+        $writer = new Ahc\Cli\Output\Writer();
+
         $this
             ->argument('<arrg>', '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
 ```
 
@@ -267,6 +274,21 @@ $app->add((new ConfigListCommand)->inGroup('Config'));
 ...
 ```
 
+#### Default command
+
+By default, running your CLI app without any arguments will show the help screen. However you can set the default action to run one of your commands either by setting the third parameter of the `add` function to `true` or by using the `defaultCommand` function.
+
+```php
+$app->add(new InitCommand, 'i', true);
+
+// Alternatively
+$app->command('init', 'Init something', 'i');
+$app->defaultCommand('init');
+
+// Retrieve the name of the default command
+$default_command = $app->getDefaultCommand();
+```
+
 #### Exception handler
 
 Set a custom exception handler as callback. The callback receives exception & exit code. The callback may rethrow exception or may exit the program or just log exception and do nothing else.
@@ -443,13 +465,48 @@ echo $color->ok('This is ok msg');
 ```php
 Ahc\Cli\Output\Color::style('mystyle', [
     'bg' => Ahc\Cli\Output\Color::CYAN,
-    'fg' => Ahc\Cli\Output\Color::WHITE,
+    'fg' => Ahc\Cli\Output\Color::fg256(57), // 256 colors can be used as well
     'bold' => 1, // You can experiment with 0, 1, 2, 3 ... as well
 ]);
 
 echo $color->mystyle('My text');
 ```
 
+#### Built-in styles
+
+There are a number of pre-defined built-in styles that allows you granular customization to different output conditions such as help and prompts:
+
+ - answer
+ - choice
+ - comment
+ - error
+ - help_category
+ - help_description_even
+ - help_description_odd
+ - help_example
+ - help_footer
+ - help_group
+ - help_header
+ - help_item_even
+ - help_item_odd
+ - help_summary
+ - help_text
+ - info
+ - logo
+ - ok
+ - question
+ - version
+ - warn
+
+Overriding a built-in style works the same way as defining a new style:
+
+```php
+Ahc\Cli\Output\Color::style('error', [
+    'fg' => Ahc\Cli\Output\Color::RED,
+    'bold' => 1,
+]);
+```
+
 ### Cursor
 
 Move cursor around, erase line up or down, clear screen.

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,16 +348,49 @@ 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}";
         $footer = 'Run `<command> --help` for specific help';
 
         if ($this->logo) {
-            $writer->write($this->logo, true);
+            $writer->logo($this->logo, true);
         }
 
         $this->outputHelper()->showCommandsHelp($this->commands(), $header, $footer);

src/Helper/OutputHelper.php

@@ -182,13 +182,13 @@ public function showCommandsHelp(array $commands, string $header = '', string $f
     protected function showHelp(string $for, array $items, string $header = '', string $footer = ''): void
     {
         if ($header) {
-            $this->writer->bold($header, true);
+            $this->writer->help_header($header, true);
         }
 
-        $this->writer->eol()->boldGreen($for . ':', true);
+        $this->writer->eol()->help_category($for . ':', true);
 
         if (empty($items)) {
-            $this->writer->bold('  (n/a)', true);
+            $this->writer->help_text('  (n/a)', true);
 
             return;
         }
@@ -197,20 +197,25 @@ protected function showHelp(string $for, array $items, string $header = '', stri
         $group = $lastGroup = null;
 
         $withDefault = $for === 'Options' || $for === 'Arguments';
-        foreach ($this->sortItems($items, $padLen, $for) as $item) {
+        foreach (array_values($this->sortItems($items, $padLen, $for)) as $idx => $item) {
             $name  = $this->getName($item);
             if ($for === 'Commands' && $lastGroup !== $group = $item->group()) {
-                $this->writer->boldYellow($group ?: '*', true);
+                $this->writer->help_group($group ?: '*', true);
                 $lastGroup = $group;
             }
             $desc  = str_replace(["\r\n", "\n"], str_pad("\n", $padLen + $space + 3), $item->desc($withDefault));
 
-            $this->writer->bold('  ' . str_pad($name, $padLen + $space));
-            $this->writer->comment($desc, true);
+            if ($idx % 2 == 0) {
+                $this->writer->help_item_even('  ' . str_pad($name, $padLen + $space));
+                $this->writer->help_description_even($desc, true);
+            } else {
+                $this->writer->help_item_odd('  ' . str_pad($name, $padLen + $space));
+                $this->writer->help_description_odd($desc, true);
+            }
         }
 
         if ($footer) {
-            $this->writer->eol()->yellow($footer, true);
+            $this->writer->eol()->help_footer($footer, true);
         }
     }
 
@@ -224,7 +229,7 @@ public function showUsage(string $usage): self
         $usage = str_replace('$0', $_SERVER['argv'][0] ?? '[cmd]', $usage);
 
         if (!str_contains($usage, ' ## ')) {
-            $this->writer->eol()->boldGreen('Usage Examples:', true)->colors($usage)->eol();
+            $this->writer->eol()->help_category('Usage Examples:', true)->colors($usage)->eol();
 
             return $this;
         }
@@ -241,7 +246,7 @@ public function showUsage(string $usage): self
             return str_pad('# ', $maxlen - array_shift($lines), ' ', STR_PAD_LEFT);
         }, $usage);
 
-        $this->writer->eol()->boldGreen('Usage Examples:', true)->colors($usage)->eol();
+        $this->writer->eol()->help_category('Usage Examples:', true)->colors($usage)->eol();
 
         return $this;
     }

src/IO/Interactor.php

@@ -38,6 +38,7 @@
  *
  * @link    https://github.com/adhocore/cli
  *
+ * @method Writer answer($text, $eol = false)
  * @method Writer bgBlack($text, $eol = false)
  * @method Writer bgBlue($text, $eol = false)
  * @method Writer bgCyan($text, $eol = false)
@@ -127,6 +128,7 @@
  * @method Writer boldYellowBgPurple($text, $eol = false)
  * @method Writer boldYellowBgRed($text, $eol = false)
  * @method Writer boldYellowBgWhite($text, $eol = false)
+ * @method Writer choice($text, $eol = false)
  * @method Writer colors($text)
  * @method Writer comment($text, $eol = false)
  * @method Writer cyan($text, $eol = false)
@@ -147,7 +149,19 @@
  * @method Writer greenBgRed($text, $eol = false)
  * @method Writer greenBgWhite($text, $eol = false)
  * @method Writer greenBgYellow($text, $eol = false)
+ * @method Writer help_category($text, $eol = false)
+ * @method Writer help_description_even($text, $eol = false)
+ * @method Writer help_description_odd($text, $eol = false)
+ * @method Writer help_example($text, $eol = false)
+ * @method Writer help_footer($text, $eol = false)
+ * @method Writer help_group($text, $eol = false)
+ * @method Writer help_header($text, $eol = false)
+ * @method Writer help_item_even($text, $eol = false)
+ * @method Writer help_item_odd($text, $eol = false)
+ * @method Writer help_summary($text, $eol = false)
+ * @method Writer help_text($text, $eol = false)
  * @method Writer info($text, $eol = false)
+ * @method Writer logo($text, $eol = false)
  * @method Writer ok($text, $eol = false)
  * @method Writer purple($text, $eol = false)
  * @method Writer purpleBgBlack($text, $eol = false)
@@ -157,6 +171,7 @@
  * @method Writer purpleBgRed($text, $eol = false)
  * @method Writer purpleBgWhite($text, $eol = false)
  * @method Writer purpleBgYellow($text, $eol = false)
+ * @method Writer question($text, $eol = false)
  * @method Writer red($text, $eol = false)
  * @method Writer redBgBlack($text, $eol = false)
  * @method Writer redBgBlue($text, $eol = false)
@@ -166,6 +181,7 @@
  * @method Writer redBgWhite($text, $eol = false)
  * @method Writer redBgYellow($text, $eol = false)
  * @method Writer table(array $rows, array $styles = [])
+ * @method Writer version($text, $eol = false)
  * @method Writer warn($text, $eol = false)
  * @method Writer white($text, $eol = false)
  * @method Writer yellow($text, $eol = false)
@@ -241,7 +257,7 @@ public function confirm(string $text, string $default = 'y'): bool
      */
     public function choice(string $text, array $choices, $default = null, bool $case = false): mixed
     {
-        $this->writer->yellow($text);
+        $this->writer->question($text);
 
         $this->listOptions($choices, $default, false);
 
@@ -262,7 +278,7 @@ public function choice(string $text, array $choices, $default = null, bool $case
      */
     public function choices(string $text, array $choices, $default = null, bool $case = false): mixed
     {
-        $this->writer->yellow($text);
+        $this->writer->question($text);
 
         $this->listOptions($choices, $default, true);
 
@@ -300,7 +316,7 @@ public function prompt(string $text, $default = null, ?callable $fn = null, int
         $hidden = func_get_args()[4] ?? false;
         $readFn = ['read', 'readHidden'][(int) $hidden];
 
-        $this->writer->yellow($text)->comment(null !== $default ? " [$default]: " : ': ');
+        $this->writer->question($text)->answer(null !== $default ? " [$default]: " : ': ');
 
         try {
             $input = $this->reader->{$readFn}($default, $fn);
@@ -310,7 +326,7 @@ public function prompt(string $text, $default = null, ?callable $fn = null, int
         }
 
         if ($retry > 0 && $input === '') {
-            $this->writer->bgRed($error, true);
+            $this->writer->error($error, true);
 
             return $this->prompt($text, $default, $fn, $retry - 1, $hidden);
         }
@@ -351,12 +367,12 @@ protected function listOptions(array $choices, $default = null, bool $multi = fa
         $maxLen = max(array_map('strlen', array_keys($choices)));
 
         foreach ($choices as $choice => $desc) {
-            $this->writer->eol()->cyan(str_pad("  [$choice]", $maxLen + 6))->comment($desc);
+            $this->writer->eol()->choice(str_pad("  [$choice]", $maxLen + 6))->answer($desc);
         }
 
         $label = $multi ? 'Choices (comma separated)' : 'Choice';
 
-        $this->writer->eol()->yellow($label);
+        $this->writer->eol()->question($label);
 
         return $this->promptOptions(array_keys($choices), $default);
     }
@@ -369,7 +385,7 @@ protected function promptOptions(array $choices, mixed $default): self
         $options = '';
 
         foreach ($choices as $choice) {
-            $style    = in_array($choice, (array) $default) ? 'boldCyan' : 'cyan';
+            $style    = in_array($choice, (array) $default) ? 'boldChoice' : 'choice';
             $options .= "/<$style>$choice</end>";
         }