Merge pull request #41 from clue-labs/autocomplete

Add autocomplete support

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,101 @@ 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',
+        'echo',
+        '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 `.
+
+If the user types `e [TAB]`, then this will match multiple entries and the user
+will be presented with a list of up to 8 available word completions to choose
+from like this:
+
+```php
+> e [TAB]
+exit  echo
+> e
+```
+
+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] ex [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 three 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 and third argument will be
+the start and end offset of this word within the complete input buffer measured
+in (Unicode) characters.
+The above examples will be invoked as `$fn('he', 0, 2)`, `$fn('e', 0, 1)` and
+`$fn('ex', 6, 8)` respectively.
+You may want to use this as an `$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 <= 1) {
+        // autocomplete root commands at offset=0/1 only
+        return array('cat', 'rm', 'stat');
+    } else {
+        // autocomplete all command arguments as glob pattern
+        return glob($word . '*', GLOB_MARK);
+    }
+});
+```
+
+> Note that the user may also use quotes and/or leading whitespace around the
+root command, for example `"hell [TAB]`, in which case the offset will be
+advanced such as this will be invoked as `$fn('hell', 1, 4)`.
+Unless you use a more sophisticated argument parser, a decent approximation may
+be using `$offset <= 1` to check this is a root command. 
+
+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

@@ -31,12 +31,17 @@
     }
 });
 
+// autocomplete the following commands (at offset=0/1 only)
+$readline->setAutocomplete(function ($_, $offset) {
+    return $offset > 1 ? array() : array('exit', 'quit', 'help', 'echo', 'print', 'printf');
+});
+
 $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/Autocomplete.php

@@ -15,7 +15,6 @@ class Readline extends EventEmitter implements ReadableStreamInterface
     private $linebuffer = '';
     private $linepos = 0;
     private $echo = true;
-    private $autocomplete = null;
     private $move = true;
     private $encoding = 'utf-8';
 
@@ -29,6 +28,9 @@ class Readline extends EventEmitter implements ReadableStreamInterface
     private $historyUnsaved = null;
     private $historyLimit = 500;
 
+    private $autocomplete = null;
+    private $autocompleteSuggestions = 8;
+
     public function __construct(ReadableStreamInterface $input, WritableStreamInterface $output)
     {
         $this->input = $input;
@@ -37,7 +39,6 @@ public function __construct(ReadableStreamInterface $input, WritableStreamInterf
         if (!$this->input->isReadable()) {
             return $this->close();
         }
-
         // push input through control code parser
         $parser = new ControlCodeParser($input);
 
@@ -387,16 +388,22 @@ public function limitHistory($limit)
     }
 
     /**
-     * set autocompletion handler to use (or none)
+     * set autocompletion handler to use
      *
      * The autocomplete handler will be called whenever the user hits the TAB
      * key.
      *
-     * @param AutocompleteInterface|null $autocomplete
+     * @param callable|null $autocomplete
      * @return self
+     * @throws InvalidArgumentException if the given callable is invalid
      */
-    public function setAutocomplete(AutocompleteInterface $autocomplete = null)
+
+    public function setAutocomplete($autocomplete)
     {
+        if ($autocomplete !== null && !is_callable($autocomplete)) {
+            throw new \InvalidArgumentException('Invalid autocomplete function given');
+        }
+
         $this->autocomplete = $autocomplete;
 
         return $this;
@@ -495,9 +502,110 @@ public function onKeyEnd()
     /** @internal */
     public function onKeyTab()
     {
-        if ($this->autocomplete !== null) {
-            $this->autocomplete->run();
+        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);
+        $start = 0;
+        $end = $this->linepos;
+
+        // buffer prefix and postfix for everything that will *not* be matched
+        // above example will return "echo " and "bar world"
+        $prefix = '';
+        $postfix = $this->substr($this->linebuffer, $this->linepos);
+
+        // skip everything before last space
+        $pos = strrpos($word, ' ');
+        if ($pos !== false) {
+            $prefix = (string)substr($word, 0, $pos + 1);
+            $word = (string)substr($word, $pos + 1);
+            $start = $this->strlen($prefix);
         }
+
+        // skip double quote (") or single quote (') from argument
+        $quote = null;
+        if (isset($word[0]) && ($word[0] === '"' || $word[0] === '\'')) {
+            $quote = $word[0];
+            ++$start;
+            $prefix .= $word[0];
+            $word = (string)substr($word, 1);
+        }
+
+        // invoke autocomplete callback
+        $words = call_user_func($this->autocomplete, $word, $start, $end);
+
+        // return early if autocomplete does not return anything
+        if ($words === null) {
+            return;
+        }
+
+        // remove from list of possible words that do not start with $word or are duplicates
+        $words = array_unique($words);
+        if ($word !== '' && $words) {
+            $words = array_filter($words, function ($w) use ($word) {
+                return strpos($w, $word) === 0;
+            });
+        }
+
+        // return if neither of the possible words match
+        if (!$words) {
+            return;
+        }
+
+        // search longest common prefix among all possible matches
+        $found = reset($words);
+        $all = count($words);
+        if ($all > 1) {
+            while ($found !== '') {
+                // count all words that start with $found
+                $matches = count(array_filter($words, function ($w) use ($found) {
+                    return strpos($w, $found) === 0;
+                }));
+
+                // ALL words match $found => common substring found
+                if ($all === $matches) {
+                    break;
+                }
+
+                // remove last letter from $found and try again
+                $found = $this->substr($found, 0, -1);
+            }
+
+            // found more than one possible match with this prefix => print options
+            if ($found === $word || $found === '') {
+                // limit number of possible matches
+                if (count($words) > $this->autocompleteSuggestions) {
+                    $more = count($words) - ($this->autocompleteSuggestions - 1);
+                    $words = array_slice($words, 0, $this->autocompleteSuggestions - 1);
+                    $words []= '(+' . $more . ' others)';
+                }
+
+                $this->output->write("\n" . implode('  ', $words) . "\n");
+                $this->redraw();
+
+                return;
+            }
+        }
+
+        if ($quote !== null && $all === 1 && (strpos($postfix, $quote) === false || strpos($postfix, $quote) > strpos($postfix, ' '))) {
+            // add closing quote if word started in quotes and postfix does not already contain closing quote before next space
+            $found .= $quote;
+        } elseif ($found === '') {
+            // add single quotes around empty match
+            $found = '\'\'';
+        }
+
+        if ($postfix === '' && $all === 1) {
+            // append single space after match unless there's a postfix or there are multiple completions
+            $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 */