feat: writes a key/value set to two columns in a row

README.md

@@ -225,7 +225,7 @@ class OtherCommand extends Ahc\Cli\Input\Command
     {
         $io = $this->app()->io();
 
-        $io->write('Other command');        
+        $io->write('Other command');
 
         // more codes ...
 
@@ -613,6 +613,55 @@ $writer->table([
 // In future we may support styling a column by its name!
 ```
 
+#### Justify content (Display setting)
+
+If you want to display certain configurations (from your .env file for example) a bit like Laravel does (via the `php artisan about` command) you can use the `justify` method.
+
+```php
+$writer->justify('Environment');
+$writer->justify('PHP Version', PHP_VERSION);
+$writer->justify('App Version', '1.0.0');
+$writer->justify('Locale', 'en');
+```
+
+Gives something like:
+
+```
+Environment ........................................
+PHP Version .................................. 8.1.4
+App Version .................................. 1.0.0
+Locale .......................................... en
+```
+
+You can use the `sep` parameter to define the separator to use.
+
+```php
+$writer->justify('Environment', '', ['sep' => '-']);
+$writer->justify('PHP Version', PHP_VERSION);
+```
+
+Gives something like:
+
+```
+Environment ----------------------------------------
+PHP Version .................................. 8.1.4
+```
+
+In addition, the text color, the background color and the thickness of the two texts can be defined via the 3rd argument of this method.
+
+```php
+$writer->justify('Cache Enable', 'true', [
+    'first' => ['fg' => Ahc\Cli\Output\Color::CYAN], // style of the key
+    'second' => ['fg' => Ahc\Cli\Output\Color::GREEN], // style of the value
+]);
+$writer->justify('Debug Mode', 'false', [
+    'first' => ['fg' => Ahc\Cli\Output\Color::CYAN], // style of the key
+    'second' => ['fg' => Ahc\Cli\Output\Color::RED], // style of the value
+]);
+```
+
+For more details regarding the different color options, see [Custom style](#custom-style)
+
 #### Reader
 
 Read and pre process user input.

src/Output/ProgressBar.php

@@ -96,7 +96,7 @@ public function __construct(?int $total = null, ?Writer $writer = null)
 
         $this->writer   = $writer ?: new Writer();
         $this->cursor   = $this->writer->cursor();
-        $this->terminal = new Terminal();
+        $this->terminal = $this->writer->terminal();
     }
 
     /**

src/Output/Writer.php

@@ -11,12 +11,15 @@
 
 namespace Ahc\Cli\Output;
 
+use Ahc\Cli\Helper\Terminal;
+
 use function fopen;
 use function fwrite;
 use function max;
 use function method_exists;
 use function str_repeat;
 use function stripos;
+use function strlen;
 use function strpos;
 use function ucfirst;
 
@@ -183,6 +186,8 @@ class Writer
 
     protected Cursor $cursor;
 
+    protected Terminal $terminal;
+
     public function __construct(string $path = null, Color $colorizer = null)
     {
         if ($path) {
@@ -194,6 +199,7 @@ public function __construct(string $path = null, Color $colorizer = null)
 
         $this->cursor    = new Cursor;
         $this->colorizer = $colorizer ?? new Color;
+        $this->terminal  = new Terminal();
     }
 
     /**
@@ -212,6 +218,14 @@ public function cursor(): Cursor
         return $this->cursor;
     }
 
+    /**
+     * Get Terminal.
+     */
+    public function terminal(): Terminal
+    {
+        return $this->terminal;
+    }
+
     /**
      * Magically set methods.
      *
@@ -288,6 +302,42 @@ public function table(array $rows, array $styles = []): self
         return $this->colors($table);
     }
 
+    /**
+     * writes a key/value set to two columns in a row
+     *
+     * @example PHP Version ............................................................. 8.1.4
+     *
+     * @param string $first The text to write in left side
+     * @param string|null $second The text to write in right side
+     * @param array $options Options to use when writing Eg: ['fg' => Color::GREEN, 'bold' => 1, 'sep' => '-']
+     *
+     * @return self
+     */
+    public function justify(string $first, ?string $second = null, array $options = []): self
+    {
+        $options = [
+            'first'  => ($options['first'] ?? []) + ['bg' => null, 'fg' => Color::WHITE, 'bold' => 0],
+            'second' => ($options['second'] ?? []) + ['bg' => null, 'fg' => Color::WHITE, 'bold' => 1],
+            'sep'    => $options['sep'] ?? '.',
+        ];
+
+        $second   = (string) $second;
+
+        $dashWidth  = $this->terminal->width() - (strlen($first) + strlen($second));
+        // remove left and right margins because we're going to add 1 space on each side (after/before the text).
+        // if we don't have a second element, we just remove the left margin
+        $dashWidth -= $second === '' ? 1 : 2;
+
+        $first = $this->colorizer->line($first, $options['first']);
+        if ($second !== '') {
+            $second = $this->colorizer->line($second, $options['second']);
+        }
+
+        $this->write($first . ' ' . str_repeat((string) $options['sep'], $dashWidth) . ' ' . $second);
+
+        return $this->eol();
+    }
+
     /**
      * Write to stdout or stderr magically.
      *

tests/Output/WriterTest.php

@@ -11,6 +11,7 @@
 
 namespace Ahc\Cli\Test\Output;
 
+use Ahc\Cli\Helper\Terminal;
 use Ahc\Cli\Output\Color;
 use Ahc\Cli\Output\Writer;
 use Ahc\Cli\Test\CliTestCase;
@@ -111,4 +112,24 @@ public function test_colorizer()
     {
         $this->assertInstanceOf(Color::class, (new Writer)->colorizer());
     }
+
+    public function test_terminal()
+    {
+        $this->assertInstanceOf(Terminal::class, (new Writer)->terminal());
+    }
+
+    public function test_justify()
+    {
+        $w = new Writer(static::$ou);
+
+        $w->justify('PHP Version', PHP_VERSION, [
+            'sep' => '-'
+        ]);
+
+        $buffer = trim($this->buffer());
+
+        $this->assertStringContainsString("PHP Version", $buffer);
+        $this->assertStringContainsString('---', $buffer);
+        $this->assertStringContainsString(PHP_VERSION, $buffer);
+    }
 }