Simplify autocomplete API, now inspired by the readline API

Author: clue

README.md

@@ -15,6 +15,7 @@ Async, event-driven and UTF-8 aware standard console input & output (STDIN, STDO
     * [Input buffer](#input-buffer)
     * [Cursor](#cursor)
     * [History](#history)
+    * [Autocomplete](#autocomplete)
   * [Advanced](#advanced)
     * [Stdout](#stdout)
     * [Stdin](#stdin)
@@ -377,6 +378,83 @@ 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*).
 
+#### Autocomplete
+
+By default, users can use autocompletion by using their TAB keys on the keyboard.
+The autocomplete function is not registered by default, thus this feature is
+effectively disabled, as the TAB key has no function then.
+
+The `setAutocomplete(?callable $autocomplete): Readline` method can be used to
+register a new autocomplete handler.
+In its most simple form, you won't need to assign any arguments and can simply
+return an array of possible word matches from a callable like this:
+
+```php
+$readline->setAutocomplete(function () {
+    return array(
+        'exit',
+        'help',
+    );
+});
+```
+
+If the user types `he [TAB]`, the first match will be skipped as it does not
+match the current word prefix and the second one will be picked automatically,
+so that the resulting input buffer is `hello `.
+
+Unless otherwise specified, the matches will be performed against the current
+word boundaries in the input buffer.
+This means that if the user types `hello [SPACE] e [TAB]`, then the resulting
+input buffer is `hello exit `, which may or may not be what you need depending
+on your particular use case.
+
+In order to give your more control over this behavior, the autocomplete function
+actually receives two arguments (similar to `ext-readline`'s
+[`readline_completion_function()`](http://php.net/manual/en/function.readline-completion-function.php)):
+The first argument will be the current incomplete word according to current
+cursor position and word boundaries, while the second argument will be the
+offset of this word within the complete input buffer.
+The first example will thus be invoked as `$fn('he', 0)`, while the second one
+will be invoked as `$fn('e', 6)`.
+You may want to use the `$offset` argument to check if the current word is an
+argument or a root command and the `$word` argument to autocomplete partial
+filename matches like this:
+
+```php
+$readline->setAutocomplete(function ($word, $offset) {
+    if ($offset === 0) {
+        // autocomplete root commands at offset=0 only
+        return array('cat', 'rm', 'stat');
+    } else {
+        // autocomplete all command arguments as glob pattern
+        return glob($word . '*', GLOB_MARK);
+    }
+});
+```
+
+If you need even more control over autocompletion, you may also want to access
+and/or manipulate the [input buffer](#input-buffer) and [cursor](#cursor)
+directly like this:
+
+```php
+$readline->setAutocomplete(function () use ($readline) {
+    if ($readline->getInput() === 'run') {
+        $readline->setInput('run --test --value=42');
+        $readline->moveCursorBy(-2);
+    }
+
+    // return empty array so normal autocompletion doesn't kick in
+    return array();
+});
+```
+
+You can use a `null` value to remove the autocomplete function again and thus
+disable the autocomplete function:
+
+```php
+$readline->setAutocomplete(null);
+```
+
 ### Advanced
 
 #### Stdout

examples/periodic.php

@@ -1,7 +1,6 @@
 <?php
 
 use Clue\React\Stdio\Stdio;
-use Clue\React\Stdio\Readline\WordAutocomplete;
 
 require __DIR__ . '/../vendor/autoload.php';
 
@@ -32,15 +31,17 @@
     }
 });
 
-$autocomplete = new WordAutocomplete(array('exit', 'quit', 'hello', 'test', 'help', 'here'));
-$stdio->getReadline()->setAutocomplete($autocomplete);
+// autocomplete the following commands (at offset=0 only)
+$readline->setAutocomplete(function ($_, $offset) {
+    return $offset ? array() : array('exit', 'quit', 'help');
+});
 
 $stdio->writeln('Will print periodic messages until you type "quit" or "exit"');
 
 $stdio->on('line', function ($line) use ($stdio, $loop, &$timer) {
     $stdio->writeln('you just said: ' . $line . ' (' . strlen($line) . ')');
 
-    if ($line === 'quit' || $line === 'exit') {
+    if (in_array(trim($line), array('quit', 'exit'))) {
         $timer->cancel();
         $stdio->end();
     }

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\Autocomplete;
-use Clue\React\Stdio\Readline\NullAutocomplete;
 
 class Readline extends EventEmitter implements ReadableStreamInterface
 {
@@ -31,15 +29,10 @@ class Readline extends EventEmitter implements ReadableStreamInterface
     private $historyUnsaved = null;
     private $historyLimit = 500;
 
-    public function __construct(ReadableStreamInterface $input, WritableStreamInterface $output, Autocomplete $autocomplete = null)
+    public function __construct(ReadableStreamInterface $input, WritableStreamInterface $output)
     {
-        if ($autocomplete === null) {
-            $autocomplete = new NullAutocomplete();
-        }
-
         $this->input = $input;
         $this->output = $output;
-        $this->autocomplete = $autocomplete;
 
         if (!$this->input->isReadable()) {
             return $this->close();
@@ -398,30 +391,22 @@ public function limitHistory($limit)
      * The autocomplete handler will be called whenever the user hits the TAB
      * key.
      *
-     * If you do not want to use autocomplet support, simply pass a `NullAutocomplete` object.
-     *
-     * @param Autocomplete $autocomplete
+     * @param callable|null $autocomplete
      * @return self
+     * @throws InvalidArgumentException if the given callable is invalid
      */
 
-    public function setAutocomplete(Autocomplete $autocomplete)
+    public function setAutocomplete($autocomplete)
     {
+        if ($autocomplete !== null && !is_callable($autocomplete)) {
+            throw new \InvalidArgumentException('Invalid autocomplete function given');
+        }
+
         $this->autocomplete = $autocomplete;
 
         return $this;
     }
 
-    /**
-     * Gets the current autocomplete handler in use
-     *
-     * @return Autocomplete
-     * @see self::setAutocomplete()
-     */
-    public function getAutocomplete()
-    {
-        return $this->autocomplete;
-    }
-
     /**
      * redraw the current input prompt
      *
@@ -515,7 +500,61 @@ public function onKeyEnd()
     /** @internal */
     public function onKeyTab()
     {
-        $this->autocomplete->go($this);
+        if ($this->autocomplete === null) {
+            return;
+        }
+
+        // current word prefix and offset for start of word in input buffer
+        // "echo foo|bar world" will return just "foo" with word offset 5
+        $word = $this->substr($this->linebuffer, 0, $this->linepos);
+        $offset = 0;
+
+        // buffer prefix and postfix for everything that will *not* be matched
+        // above example will return "echo " and "bar world"
+        $prefix = '';
+        $postfix = (string)$this->substr($this->linebuffer, $this->linepos);
+
+        // skip everything before last space
+        $pos = strrpos($word, ' ');
+        if ($pos !== false) {
+            $offset = $pos + 1;
+            $prefix = (string)substr($word, 0, $pos + 1);
+            $word = (string)substr($word, $pos + 1);
+        }
+
+        // invoke automcomplete callback
+        $words = call_user_func($this->autocomplete, $word, $offset);
+
+        // return early if autocomplete does not return anything
+        if ($words === null) {
+            return;
+        }
+
+        // remove all from list of possible words that do not start with $word
+        $len = strlen($word);
+        foreach ($words as $i => $w) {
+            if ($word !== substr($w, 0, $len)) {
+                unset($words[$i]);
+            }
+        }
+
+        // return if neither of the possible words match
+        if (!$words) {
+            return;
+        }
+
+        // TODO: find the BEST match
+        // TODO: always picks first match for now
+        $found = reset($words);
+
+        // append single space after this argument unless there's a postfix
+        if ($postfix === '') {
+            $found .= ' ';
+        }
+
+        // replace word in input with best match and adjust cursor
+        $this->linebuffer = $prefix . $found . $postfix;
+        $this->moveCursorBy($this->strlen($found) - $this->strlen($word));
     }
 
     /** @internal */