Add addInput() helper method

Author: clue

README.md

@@ -224,10 +224,25 @@ $readline->setEcho(true);
 Everything the user types will be buffered in the current *user input buffer*.
 Once the user hits enter, the *user input buffer* will be processed and cleared.
 
+The `addInput($input)` method can be used to add text to the *user input
+buffer* at the current cursor position.
+The given text will be inserted just like the user would type in a text and as
+such adjusts the current cursor position accordingly.
+The user will be able to delete and/or rewrite the buffer at any time.
+Changing the *user input buffer* can be useful for presenting a preset input to
+the usser (like the last password attempt).
+Simply pass an input string like this:
+
+```php
+$readline->addInput('hello');
+```
+
 The `setInput($buffer)` method can be used to control the *user input buffer*.
+The given text will be used to replace the entire current *user input buffer*
+and as such adjusts the current cursor position to the end of the new buffer.
 The user will be able to delete and/or rewrite the buffer at any time.
-Changing the *user input buffer* can be useful for presenting a preset input to the user
-(like the last password attempt).
+Changing the *user input buffer* can be useful for presenting a preset input to
+the user (like the last password attempt).
 Simply pass an input string like this:
 
 ```php

src/Readline.php

@@ -276,6 +276,36 @@ public function moveCursorTo($n)
         return $this;
     }
 
+    /**
+     * Appends the given input to the current text input buffer at the current position
+     *
+     * This moves the cursor accordingly to the number of characters added.
+     *
+     * @param string $input
+     * @return self
+     * @uses self::redraw()
+     */
+    public function addInput($input)
+    {
+        if ($input === '') {
+            return $this;
+        }
+
+        // read everything up until before current position
+        $pre  = $this->substr($this->linebuffer, 0, $this->linepos);
+        $post = $this->substr($this->linebuffer, $this->linepos);
+
+        $this->linebuffer = $pre . $input . $post;
+        $this->linepos += $this->strlen($input);
+
+        // only redraw if input should be echo'ed (i.e. is not hidden anyway)
+        if ($this->echo !== false) {
+            $this->redraw();
+        }
+
+        return $this;
+    }
+
     /**
      * set current text input buffer
      *
@@ -694,14 +724,7 @@ public function onKeyDown()
      */
     public function onFallback($chars)
     {
-        // read everything up until before current position
-        $pre  = $this->substr($this->linebuffer, 0, $this->linepos);
-        $post = $this->substr($this->linebuffer, $this->linepos);
-
-        $this->linebuffer = $pre . $chars . $post;
-        $this->linepos += $this->strlen($chars);
-
-        $this->redraw();
+        $this->addInput($chars);
     }
 
     /**

tests/ReadlineTest.php

@@ -40,6 +40,27 @@ public function testGetInputAfterSetting()
         $this->assertEquals(5, $this->readline->getCursorCell());
     }
 
+    public function testAddInputAfterSetting()
+    {
+        $this->readline->setInput('hello');
+
+        $this->assertSame($this->readline, $this->readline->addInput(' world'));
+        $this->assertEquals('hello world', $this->readline->getInput());
+        $this->assertEquals(11, $this->readline->getCursorPosition());
+        $this->assertEquals(11, $this->readline->getCursorCell());
+    }
+
+    public function testAddInputAfterSettingCurrentCursorPosition()
+    {
+        $this->readline->setInput('hello');
+        $this->readline->moveCursorTo(2);
+
+        $this->assertSame($this->readline, $this->readline->addInput('ha'));
+        $this->assertEquals('hehallo', $this->readline->getInput());
+        $this->assertEquals(4, $this->readline->getCursorPosition());
+        $this->assertEquals(4, $this->readline->getCursorCell());
+    }
+
     public function testPromptAfterSetting()
     {
         $this->assertSame($this->readline, $this->readline->setPrompt('> '));
@@ -180,6 +201,22 @@ public function testSettingInputWithoutEchoDoesNotNeedToRedraw()
         $this->assertSame($this->readline, $this->readline->setInput('test'));
     }
 
+    public function testAddingEmptyInputDoesNotNeedToRedraw()
+    {
+        $this->output->expects($this->never())->method('write');
+
+        $this->assertSame($this->readline, $this->readline->addInput(''));
+    }
+
+    public function testAddingInputWithoutEchoDoesNotNeedToRedraw()
+    {
+        $this->readline->setEcho(false);
+
+        $this->output->expects($this->never())->method('write');
+
+        $this->assertSame($this->readline, $this->readline->addInput('test'));
+    }
+
     public function testMovingCursorWithoutEchoDoesNotNeedToRedraw()
     {
         $this->readline->setEcho(false);