From 8ba6258e0a3d17e7baac6f33e61cc5c69f247efb Mon Sep 17 00:00:00 2001
From: Lonnie Ezell <lonnieje@gmail.com>
Date: Tue, 2 Apr 2019 23:14:27 -0500
Subject: [PATCH] Added print method to CLI library so you can print multiple
 times on the same line.

---
 system/CLI/CLI.php                        | 39 +++++++++++++++++++++--
 tests/system/CLI/CLITest.php              | 25 +++++++++++++++
 user_guide_src/source/cli/cli_library.rst | 12 +++++++
 3 files changed, 74 insertions(+), 2 deletions(-)

diff --git a/system/CLI/CLI.php b/system/CLI/CLI.php
index 042155e1c512..68614ce87718 100644
--- a/system/CLI/CLI.php
+++ b/system/CLI/CLI.php
@@ -140,6 +140,15 @@ class CLI
 	 */
 	protected static $options = [];
 
+	/**
+	 * Helps track internally whether the last
+	 * output was a "write" or a "print" to
+	 * keep the output clean and as expected.
+	 *
+	 * @var string
+	 */
+	protected static $lastWrite;
+
 	//--------------------------------------------------------------------
 
 	/**
@@ -291,7 +300,27 @@ protected static function validate(string $field, string $value, string $rules):
 	//--------------------------------------------------------------------
 
 	/**
-	 * Outputs a string to the cli.
+	 * Outputs a string to the CLI without any surrounding newlines.
+	 * Useful for showing repeating elements on a single line.
+	 *
+	 * @param string      $text
+	 * @param string|null $foreground
+	 * @param string|null $background
+	 */
+	public static function print(string $text = '', string $foreground = null, string $background = null)
+	{
+		if ($foreground || $background)
+		{
+			$text = static::color($text, $foreground, $background);
+		}
+
+		static::$lastWrite = null;
+
+		fwrite(STDOUT, $text);
+	}
+
+	/**
+	 * Outputs a string to the cli on it's own line.
 	 *
 	 * @param string $text       The text to output
 	 * @param string $foreground
@@ -304,6 +333,12 @@ public static function write(string $text = '', string $foreground = null, strin
 			$text = static::color($text, $foreground, $background);
 		}
 
+		if (static::$lastWrite !== 'write')
+		{
+			$text              = PHP_EOL . $text;
+			static::$lastWrite = 'write';
+		}
+
 		fwrite(STDOUT, $text . PHP_EOL);
 	}
 
@@ -482,7 +517,7 @@ public static function color(string $text, string $foreground, string $backgroun
 	 * Get the number of characters in string having encoded characters
 	 * and ignores styles set by the color() function
 	 *
-	 * @param ?string $string
+	 * @param string $string
 	 *
 	 * @return integer
 	 */
diff --git a/tests/system/CLI/CLITest.php b/tests/system/CLI/CLITest.php
index e641bc24395d..b4f9ae5f1ca4 100644
--- a/tests/system/CLI/CLITest.php
+++ b/tests/system/CLI/CLITest.php
@@ -99,10 +99,35 @@ public function testColor()
 		$this->assertEquals("\033[1;37m\033[42m\033[4mtest\033[0m", CLI::color('test', 'white', 'green', 'underline'));
 	}
 
+	public function testPrint()
+	{
+		CLI::print('test');
+		$expected = 'test';
+
+		$this->assertEquals($expected, CITestStreamFilter::$buffer);
+	}
+
+	public function testPrintForeground()
+	{
+		CLI::print('test', 'red');
+		$expected = "\033[0;31mtest\033[0m";
+
+		$this->assertEquals($expected, CITestStreamFilter::$buffer);
+	}
+
+	public function testPrintBackground()
+	{
+		CLI::print('test', 'red', 'green');
+		$expected = "\033[0;31m\033[42mtest\033[0m";
+
+		$this->assertEquals($expected, CITestStreamFilter::$buffer);
+	}
+
 	public function testWrite()
 	{
 		CLI::write('test');
 		$expected = <<<EOT
+
 test
 
 EOT;
diff --git a/user_guide_src/source/cli/cli_library.rst b/user_guide_src/source/cli/cli_library.rst
index 0c256b8d7c6b..ff2d947fe63c 100644
--- a/user_guide_src/source/cli/cli_library.rst
+++ b/user_guide_src/source/cli/cli_library.rst
@@ -106,6 +106,18 @@ And a smaller number are available as background colors:
 * light_gray
 * magenta
 
+**print()**
+
+Print functions identically to the ``write()`` method, except that it does not force a newline either before or after.
+Instead it prints it to the screen wherever the cursor is currently. This allows you to print multiple items all on
+the same line, from different calls. This is especially helpful when you want to show a status, do something, then
+print "Done" on the same line::
+
+    for ($i = 0; $i <= 10; $i++)
+    {
+        CLI::print($i);
+    }
+
 **color()**
 
 While the ``write()`` command will write a single line to the terminal, ending it with a EOL character, you can