Show list of available word completions if multiple match

Author: clue

README.md

@@ -393,6 +393,7 @@ return an array of possible word matches from a callable like this:
 $readline->setAutocomplete(function () {
     return array(
         'exit',
+        'echo',
         'help',
     );
 });
@@ -402,9 +403,19 @@ 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] e [TAB]`, then the resulting
+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.
 
@@ -414,8 +425,8 @@ actually receives two arguments (similar to `ext-readline`'s
 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)`.
+The above examples will be invoked as `$fn('he', 0)`, `$fn('e', 0)` and
+`$fn('ex', 6)` respectively.
 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:

examples/periodic.php

@@ -33,7 +33,7 @@
 
 // autocomplete the following commands (at offset=0 only)
 $readline->setAutocomplete(function ($_, $offset) {
-    return $offset ? array() : array('exit', 'quit', 'help');
+    return $offset ? array() : array('exit', 'quit', 'help', 'echo', 'print', 'printf');
 });
 
 $stdio->writeln('Will print periodic messages until you type "quit" or "exit"');

src/Readline.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;
@@ -546,30 +548,39 @@ public function onKeyTab()
 
         // search longest common prefix among all possible matches
         $found = reset($words);
-        array_shift($words);
-        $others = count($words);
+        $all = count($words);
         while ($found !== $word) {
             // count all words that start with $found
             $matches = count(array_filter($words, function ($word) use ($found) {
                 return strpos($word, $found) === 0;
             }));
 
             // ALL words match $found => common substring found
-            if ($others === $matches) {
+            if ($all === $matches) {
                 break;
             }
 
             // remove last letter from $found and try again
             $found = (string)substr($found, 0, -1);
         }
 
-        // current prefix has multiple possible completions => abort
-        if ($found === $word && $others) {
+        // found more than once possible match with this prefix => print options
+        if ($found === $word && $all > 1) {
+            // 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;
         }
 
         // append single space after match unless there's a postfix or there are multiple completions
-        if ($postfix === '' && $others === 0) {
+        if ($postfix === '' && $all === 1) {
             $found .= ' ';
         }
 

tests/ReadlineTest.php

@@ -651,6 +651,64 @@ public function testAutocompleteUsesCommonPrefixWhenMultipleMatchAndEnd()
         $this->assertEquals('count', $this->readline->getInput());
     }
 
+    public function testAutocompleteShowsAvailableOptionsWhenMultipleMatch()
+    {
+        $buffer = '';
+        $this->output->expects($this->atLeastOnce())->method('write')->will($this->returnCallback(function ($data) use (&$buffer) {
+            $buffer .= $data;
+        }));
+
+        $this->readline->setAutocomplete(function () { return array('a', 'b'); });
+
+        $this->readline->onKeyTab();
+
+        $this->assertContains("\na  b\n", $buffer);
+    }
+
+    public function testAutocompleteShowsAvailableOptionsWhenMultipleMatchIncompleteWord()
+    {
+        $buffer = '';
+        $this->output->expects($this->atLeastOnce())->method('write')->will($this->returnCallback(function ($data) use (&$buffer) {
+            $buffer .= $data;
+        }));
+
+        $this->readline->setAutocomplete(function () { return array('hello', 'hellö'); });
+
+        $this->readline->setInput('hell');
+
+        $this->readline->onKeyTab();
+
+        $this->assertContains("\nhello  hellö\n", $buffer);
+    }
+
+    public function testAutocompleteShowsAvailableOptionsWithoutDuplicatesWhenMultipleMatch()
+    {
+        $buffer = '';
+        $this->output->expects($this->atLeastOnce())->method('write')->will($this->returnCallback(function ($data) use (&$buffer) {
+            $buffer .= $data;
+        }));
+
+        $this->readline->setAutocomplete(function () { return array('a', 'b', 'b', 'a'); });
+
+        $this->readline->onKeyTab();
+
+        $this->assertContains("\na  b\n", $buffer);
+    }
+
+    public function testAutocompleteShowsLimitedNumberOfAvailableOptionsWhenMultipleMatch()
+    {
+        $buffer = '';
+        $this->output->expects($this->atLeastOnce())->method('write')->will($this->returnCallback(function ($data) use (&$buffer) {
+            $buffer .= $data;
+        }));
+
+        $this->readline->setAutocomplete(function () { return range('a', 'z'); });
+
+        $this->readline->onKeyTab();
+
+        $this->assertContains("\na  b  c  d  e  f  g  (+19 others)\n", $buffer);
+    }
+
     public function testEmitEmptyInputOnEnter()
     {
         $this->readline->on('data', $this->expectCallableOnceWith(''));