Symbol and keyword readline completers (#340)

* Install a Readline completer function for symbols and keywords

* Support readline history

* Formatting

* Test for keyword completions

* Tests for Namespace completions

Author: chrisrink10

src/basilisp/cli.py

@@ -1,7 +1,6 @@
+import atexit
 import importlib
-
-# noinspection PyUnresolvedReferences
-import readline  # noqa: F401
+import os.path
 import traceback
 import types
 from typing import Any
@@ -16,9 +15,31 @@
 import basilisp.main as basilisp
 
 CLI_INPUT_FILE_PATH = "<CLI Input>"
+BASILISP_REPL_HISTORY_FILE_PATH = os.path.join(
+    os.path.expanduser("~"), ".basilisp_history"
+)
+BASILISP_REPL_HISTORY_LENGTH = 1000
 REPL_INPUT_FILE_PATH = "<REPL Input>"
 
 
+try:
+    import readline
+except ImportError:
+    pass
+else:
+    readline.parse_and_bind("tab: complete")
+    readline.set_completer_delims("()[]{} \n\t")
+    readline.set_completer(runtime.repl_complete)
+
+    try:
+        readline.read_history_file(BASILISP_REPL_HISTORY_FILE_PATH)
+        readline.set_history_length(BASILISP_REPL_HISTORY_LENGTH)
+    except FileNotFoundError:
+        pass
+
+    atexit.register(readline.write_history_file, BASILISP_REPL_HISTORY_FILE_PATH)
+
+
 @click.group()
 def cli():
     """Basilisp is a Lisp dialect inspired by Clojure targeting Python 3."""

src/basilisp/lang/keyword.py

@@ -1,12 +1,12 @@
-from typing import Optional
+from typing import Optional, Iterable
 
 from pyrsistent import pmap, PMap
 
 import basilisp.lang.associative as lassoc
 import basilisp.lang.atom as atom
 from basilisp.lang.obj import LispObject
 
-__INTERN = atom.Atom(pmap())
+__INTERN: atom.Atom["PMap[int, Keyword]"] = atom.Atom(pmap())
 
 
 class Keyword(LispObject):
@@ -42,7 +42,34 @@ def __call__(self, m: lassoc.Associative, default=None):
             return None
 
 
-def __get_or_create(kw_cache: PMap, h: int, name: str, ns: Optional[str]) -> PMap:
+def complete(
+    text: str, kw_cache: atom.Atom["PMap[int, Keyword]"] = __INTERN
+) -> Iterable[str]:
+    """Return an iterable of possible completions for the given text."""
+    assert text.startswith(":")
+    interns = kw_cache.deref()
+    text = text[1:]
+
+    if "/" in text:
+        prefix, suffix = text.split("/", maxsplit=1)
+        results = filter(
+            lambda kw: (kw.ns is not None and kw.ns == prefix)
+            and kw.name.startswith(suffix),
+            interns.itervalues(),
+        )
+    else:
+        results = filter(
+            lambda kw: kw.name.startswith(text)
+            or (kw.ns is not None and kw.ns.startswith(text)),
+            interns.itervalues(),
+        )
+
+    return map(str, results)
+
+
+def __get_or_create(
+    kw_cache: "PMap[int, Keyword]", h: int, name: str, ns: Optional[str]
+) -> PMap:
     """Private swap function used to either get the interned keyword
     instance from the input string."""
     if h in kw_cache:
@@ -52,7 +79,9 @@ def __get_or_create(kw_cache: PMap, h: int, name: str, ns: Optional[str]) -> PMa
 
 
 def keyword(
-    name: str, ns: Optional[str] = None, kw_cache: atom.Atom = __INTERN
+    name: str,
+    ns: Optional[str] = None,
+    kw_cache: atom.Atom["PMap[int, Keyword]"] = __INTERN,
 ) -> Keyword:
     """Create a new keyword."""
     h = hash((name, ns))

src/basilisp/lang/runtime.py

@@ -4,10 +4,11 @@
 import itertools
 import logging
 import math
+import re
 import threading
 import types
 from fractions import Fraction
-from typing import Optional, Dict, Tuple, Union, Any, Callable
+from typing import Optional, Dict, Tuple, Union, Any, Callable, Iterable
 
 import basilisp.lang.associative as lassoc
 import basilisp.lang.collection as lcoll
@@ -80,6 +81,9 @@
     _VAR,
 )
 
+CompletionMatcher = Callable[[Tuple[sym.Symbol, Any]], bool]
+CompletionTrimmer = Callable[[Tuple[sym.Symbol, Any]], str]
+
 
 def _new_module(name: str, doc=None) -> types.ModuleType:
     """Create a new empty Basilisp Python module.
@@ -541,6 +545,108 @@ def remove(cls, name: sym.Symbol) -> Optional["Namespace"]:
             if cls._NAMESPACES.compare_and_set(oldval, newval):
                 return ns
 
+    # REPL Completion support
+
+    @staticmethod
+    def __completion_matcher(text: str) -> CompletionMatcher:
+        """Return a function which matches any symbol keys from map entries
+        against the given text."""
+
+        def is_match(entry: Tuple[sym.Symbol, Any]) -> bool:
+            return entry[0].name.startswith(text)
+
+        return is_match
+
+    def __complete_alias(
+        self, prefix: str, name_in_ns: Optional[str] = None
+    ) -> Iterable[str]:
+        """Return an iterable of possible completions matching the given
+        prefix from the list of aliased namespaces. If name_in_ns is given,
+        further attempt to refine the list to matching names in that namespace."""
+        candidates: Iterable[Tuple[sym.Symbol, Namespace]] = filter(
+            Namespace.__completion_matcher(prefix), self.aliases
+        )
+        if name_in_ns is not None:
+            for _, candidate_ns in candidates:
+                for match in candidate_ns.__complete_interns(
+                    name_in_ns, include_private_vars=False
+                ):
+                    yield f"{prefix}/{match}"
+        else:
+            for alias, _ in candidates:
+                yield f"{alias}/"
+
+    def __complete_imports_and_aliases(
+        self, prefix: str, name_in_module: Optional[str] = None
+    ) -> Iterable[str]:
+        """Return an iterable of possible completions matching the given
+        prefix from the list of imports and aliased imports. If name_in_module
+        is given, further attempt to refine the list to matching names in that
+        namespace."""
+        imports = self.imports
+        aliases = lmap.map(
+            {
+                alias: imports.entry(import_name)
+                for alias, import_name in self.import_aliases
+            }
+        )
+
+        candidates: Iterable[Tuple[sym.Symbol, types.ModuleType]] = filter(
+            Namespace.__completion_matcher(prefix), itertools.chain(aliases, imports)
+        )
+        if name_in_module is not None:
+            for _, module in candidates:
+                for name in module.__dict__:
+                    if name.startswith(name_in_module):
+                        yield f"{prefix}/{name}"
+        else:
+            for candidate_name, _ in candidates:
+                yield f"{candidate_name}/"
+
+    def __complete_interns(
+        self, value: str, include_private_vars: bool = True
+    ) -> Iterable[str]:
+        """Return an iterable of possible completions matching the given
+        prefix from the list of interned Vars."""
+        if include_private_vars:
+            is_match = Namespace.__completion_matcher(value)
+        else:
+            _is_match = Namespace.__completion_matcher(value)
+
+            def is_match(entry: Tuple[sym.Symbol, Var]) -> bool:
+                return _is_match(entry) and not entry[1].is_private
+
+        return map(lambda entry: f"{entry[0].name}", filter(is_match, self.interns))
+
+    def __complete_refers(self, value: str) -> Iterable[str]:
+        """Return an iterable of possible completions matching the given
+        prefix from the list of referred Vars."""
+        return map(
+            lambda entry: f"{entry[0].name}",
+            filter(Namespace.__completion_matcher(value), self.refers),
+        )
+
+    def complete(self, text: str) -> Iterable[str]:
+        """Return an iterable of possible completions for the given text in
+        this namespace."""
+        assert not text.startswith(":")
+
+        if "/" in text:
+            prefix, suffix = text.split("/", maxsplit=1)
+            results = itertools.chain(
+                self.__complete_alias(prefix, name_in_ns=suffix),
+                self.__complete_imports_and_aliases(prefix, name_in_module=suffix),
+            )
+        else:
+            results = itertools.chain(
+                self.__complete_alias(text),
+                self.__complete_imports_and_aliases(text),
+                self.__complete_interns(text),
+                self.__complete_refers(text),
+            )
+
+        return results
+
 
 ###################
 # Runtime Support #
@@ -944,6 +1050,23 @@ def lstr(o) -> str:
     return lrepr(o, human_readable=True)
 
 
+__NOT_COMPLETEABLE = re.compile(r"^[0-9].*")
+
+
+def repl_complete(text: str, state: int) -> Optional[str]:
+    """Completer function for Python's readline/libedit implementation."""
+    # Can't complete Keywords, Numerals
+    if __NOT_COMPLETEABLE.match(text):
+        return None
+    elif text.startswith(":"):
+        completions = kw.complete(text)
+    else:
+        ns = get_current_ns()
+        completions = ns.complete(text)
+
+    return list(completions)[state] if completions is not None else None
+
+
 def _collect_args(args) -> lseq.Seq:
     """Collect Python starred arguments into a Basilisp list."""
     if isinstance(args, tuple):

tests/basilisp/keyword_test.py

@@ -1,5 +1,9 @@
+import pytest
+from pyrsistent import PMap, pmap
+
 import basilisp.lang.map as lmap
-from basilisp.lang.keyword import keyword
+from basilisp.lang.atom import Atom
+from basilisp.lang.keyword import Keyword, keyword, complete
 
 
 def test_keyword_identity_equals():
@@ -41,3 +45,32 @@ def test_keyword_as_function():
     assert 1 == kw(lmap.map({kw: 1}))
     assert "hi" == kw(lmap.map({kw: "hi"}))
     assert None is kw(lmap.map({"hi": kw}))
+
+
+class TestKeywordCompletion:
+    @pytest.fixture
+    def empty_cache(self) -> Atom["PMap[int, Keyword]"]:
+        return Atom(pmap())
+
+    def test_empty_cache_no_completion(self, empty_cache: Atom["PMap[int, Keyword]"]):
+        assert [] == list(complete(":", kw_cache=empty_cache))
+
+    @pytest.fixture
+    def cache(self) -> Atom["PMap[int, Keyword]"]:
+        values = [Keyword("kw"), Keyword("ns"), Keyword("kw", ns="ns")]
+        return Atom(pmap({hash(v): v for v in values}))
+
+    def test_no_ns_completion(self, cache: Atom["PMap[int, Keyword]"]):
+        assert [] == list(complete(":v", kw_cache=cache))
+        assert {":kw", ":ns/kw"} == set(complete(":k", kw_cache=cache))
+        assert {":kw", ":ns/kw"} == set(complete(":kw", kw_cache=cache))
+        assert {":ns", ":ns/kw"} == set(complete(":n", kw_cache=cache))
+        assert {":ns", ":ns/kw"} == set(complete(":ns", kw_cache=cache))
+
+    def test_ns_completion(self, cache: Atom["PMap[int, Keyword]"]):
+        assert [] == list(complete(":v/", kw_cache=cache))
+        assert [] == list(complete(":k/", kw_cache=cache))
+        assert [] == list(complete(":kw/", kw_cache=cache))
+        assert [] == list(complete(":n/", kw_cache=cache))
+        assert [":ns/kw"] == list(complete(":ns/", kw_cache=cache))
+        assert [":ns/kw"] == list(complete(":ns/k", kw_cache=cache))

tests/basilisp/namespace_test.py

@@ -293,3 +293,52 @@ def test_alias(ns_cache: patch):
 
         assert None is ns1.get_alias(sym.symbol("ns2"))
         assert ns2 is ns1.get_alias(sym.symbol("n2"))
+
+
+class TestCompletion:
+    @pytest.fixture
+    def ns(self) -> Namespace:
+        ns_sym = sym.symbol("test")
+        ns = Namespace(ns_sym)
+
+        str_ns_alias = sym.symbol("basilisp.string")
+        join_sym = sym.symbol("join")
+        chars_sym = sym.symbol("chars")
+        str_ns = Namespace(str_ns_alias)
+        str_ns.intern(join_sym, Var(ns, join_sym))
+        str_ns.intern(
+            chars_sym, Var(ns, chars_sym, meta=lmap.map({kw.keyword("private"): True}))
+        )
+        ns.add_alias(str_ns_alias, str_ns)
+
+        str_alias = sym.symbol("str")
+        ns.add_alias(str_alias, Namespace(str_alias))
+
+        str_sym = sym.symbol("str")
+        ns.intern(str_sym, Var(ns, str_sym))
+
+        is_string_sym = sym.symbol("string?")
+        ns.intern(is_string_sym, Var(ns, is_string_sym))
+
+        time_sym = sym.symbol("time")
+        time_alias = sym.symbol("py-time")
+        ns.add_import(time_sym, __import__("time"), time_alias)
+
+        core_ns = Namespace(sym.symbol("basilisp.core"))
+        map_alias = sym.symbol("map")
+        ns.add_refer(map_alias, Var(core_ns, map_alias))
+
+        return ns
+
+    def test_ns_completion(self, ns: Namespace):
+        assert {"basilisp.string/"} == set(ns.complete("basilisp.st"))
+        assert {"basilisp.string/join"} == set(ns.complete("basilisp.string/j"))
+        assert {"str/", "string?", "str"} == set(ns.complete("st"))
+        assert {"map"} == set(ns.complete("m"))
+        assert {"map"} == set(ns.complete("ma"))
+
+    def test_import_and_alias(self, ns: Namespace):
+        assert {"time/"} == set(ns.complete("ti"))
+        assert {"time/asctime"} == set(ns.complete("time/as"))
+        assert {"py-time/"} == set(ns.complete("py-t"))
+        assert {"py-time/asctime"} == set(ns.complete("py-time/as"))