Simplify history API, now inspired by the readline API

Author: clue

README.md

@@ -14,6 +14,7 @@ Async, event-driven and UTF-8 aware standard console input & output (STDIN, STDO
     * [Echo](#echo)
     * [Input buffer](#input-buffer)
     * [Cursor](#cursor)
+    * [History](#history)
   * [Advanced](#advanced)
     * [Stdout](#stdout)
     * [Stdin](#stdin)
@@ -283,6 +284,57 @@ For example, to move the cursor one character to the left, simply call:
 $readline->moveCursorBy(-1);
 ```
 
+#### History
+
+By default, users can access the history of previous commands by using their
+UP and DOWN cursor keys on the keyboard.
+The history will start with an empty state, thus this feature is effectively
+disabled, as the UP and DOWN cursor keys have no function then.
+
+The `listHistory(): string[]` method can be used to
+return an array with all lines in the history.
+This will be an empty array until you add new entries via `addHistory()`.
+
+```php
+$list = $readline->listHistory();
+
+assert(count($list) === 0);
+```
+
+The `addHistory(string $line): Readline` method can be used to
+add a new line to the (bottom position of the) history list.
+A following `listHistory()` call will return this line as the last element.
+
+```php
+$readline->addHistory('a');
+$readline->addHistory('b');
+
+$list = $readline->listHistory();
+assert($list === array('a', 'b'));
+```
+
+The `clearHistory(): Readline` method can be used to
+clear the complete history list.
+A following `listHistory()` call will return an empty array until you add new
+entries via `addHistory()` again.
+Note that the history feature will effectively be disabled if the history is
+empty, as the UP and DOWN cursor keys have no function then.
+
+```php
+$readline->clearHistory();
+
+$list = $readline->listHistory();
+assert(count($list) === 0);
+```
+
+There is no such thing as a `readHistory()` or `writeHistory()` method
+because filesystem operations are inherently blocking and thus beyond the scope
+of this library.
+Using your favorite filesystem API and an appropriate number of `addHistory()`
+or a single `listHistory()` call respectively should be fairly straight
+forward and is left up as an exercise for the reader of this documentation
+(i.e. *you*).
+
 ### Advanced
 
 #### Stdout

src/Readline.php

@@ -8,8 +8,6 @@
 use React\Stream\Util;
 use Clue\React\Utf8\Sequencer as Utf8Sequencer;
 use Clue\React\Term\ControlCodeParser;
-use Clue\React\Stdio\Readline\History;
-use Clue\React\Stdio\Readline\MemoryHistory;
 
 class Readline extends EventEmitter implements ReadableStreamInterface
 {
@@ -19,24 +17,21 @@ class Readline extends EventEmitter implements ReadableStreamInterface
     private $echo = true;
     private $autocomplete = null;
     private $move = true;
-    private $history;
     private $encoding = 'utf-8';
 
     private $input;
     private $output;
     private $sequencer;
     private $closed = false;
 
-    public function __construct(ReadableStreamInterface $input, WritableStreamInterface $output, History $history = null)
+    private $historyLines = array();
+    private $historyPosition = null;
+    private $historyUnsaved = null;
+
+    public function __construct(ReadableStreamInterface $input, WritableStreamInterface $output)
     {
         $this->input = $input;
-
-        if ($history === null) {
-            $history = new MemoryHistory();
-        }
-
         $this->output = $output;
-        $this->history = $history;
 
         if (!$this->input->isReadable()) {
             return $this->close();
@@ -319,32 +314,44 @@ public function getInput()
     }
 
     /**
-     * set history handler to use
+     * Adds a new line to the (bottom position of the) history list
      *
-     * The history handler will be called whenever the user hits the UP or DOWN
-     * arrow keys.
-     *
-     * If you do not want to use history support, simply pass a `NullHistory` object.
+     * @param string $line
+     * @return self
+     */
+    public function addHistory($line)
+    {
+        $this->historyLines []= $line;
+
+        return $this;
+    }
+
+    /**
+     * Clears the complete history list
      *
-     * @param History $history new history handler to use
      * @return self
      */
-    public function setHistory(History $history)
+    public function clearHistory()
     {
-        $this->history = $history;
+        $this->historyLines = array();
+        $this->historyPosition = null;
+
+        if ($this->historyUnsaved !== null) {
+            $this->setInput($this->historyUnsaved);
+            $this->historyUnsaved = null;
+        }
 
         return $this;
     }
 
     /**
-     * Gets the current history handler in use
+     * Returns an array with all lines in the history
      *
-     * @return History
-     * @see self::setHistory()
+     * @return string[]
      */
-    public function getHistory()
+    public function listHistory()
     {
-        return $this->history;
+        return $this->historyLines;
     }
 
     /**
@@ -489,13 +496,40 @@ public function onKeyRight()
     /** @internal */
     public function onKeyUp()
     {
-        $this->history->moveUp($this);
+        // ignore if already at top or history is empty
+        if ($this->historyPosition === 0 || !$this->historyLines) {
+            return;
+        }
+
+        if ($this->historyPosition === null) {
+            // first time up => move to last entry
+            $this->historyPosition = count($this->historyLines) - 1;
+            $this->historyUnsaved = $this->getInput();
+        } else {
+            // somewhere in the list => move by one
+            $this->historyPosition--;
+        }
+
+        $this->setInput($this->historyLines[$this->historyPosition]);
     }
 
     /** @internal */
     public function onKeyDown()
     {
-        $this->history->moveDown($this);
+        // ignore if not currently cycling through history
+        if ($this->historyPosition === null) {
+            return;
+        }
+
+        if (($this->historyPosition + 1) < count($this->historyLines)) {
+            // this is still a valid position => advance by one and apply
+            $this->historyPosition++;
+            $this->setInput($this->historyLines[$this->historyPosition]);
+        } else {
+            // moved beyond bottom => restore original unsaved input
+            $this->setInput($this->historyUnsaved);
+            $this->historyPosition = null;
+        }
     }
 
     /**
@@ -565,7 +599,9 @@ protected function processLine()
         }
 
         // process stored input buffer
-        $this->history->addLine($line);
+        if ($line !== '') {
+            $this->addHistory($line);
+        }
         $this->emit('data', array($line));
     }