Custom sources

Compliment uses a flexible system of completion sources. This allows library developers to write custom sources for completion that makes sense in the context of their libraries.

Creating a completion source

A completion source defines two functions: candidates and documentation. The former returns a list of completion candidates for the given prefix, the latter returns a documentation string for the given symbol.

Here are their signatures:

(defn candidates [^String prefix, ^Namespace ns, context])

(defn doc [^String symbol-str, ^Namespace ns])

For understanding what context is and how to use it in your custom source see Context page.

You can view the examples of these functions in Compliment’s own default sources.

Injecting the source into Compliment

After you have defined these two functions, you need to somehow tell Compliment to use them. This can be done by calling (compliment.sources/defsource) function.

defsource takes a name for the source (usually a namespace-qualified keyword) and two key-value pairs for :candidates and :doc.

But keep in mind that the user of your library might not use Compliment, so you should not explicitly depend on Compliment namespaces, but rather try to resolve them in runtime.

Here is the example from Neko library:

;; candidates and doc are two already defined functions.
(defn init-source []
  (try (require 'compliment.core)
       ((resolve 'compliment.sources/defsource) ::android-resources
        :candidates #'candidates
        :doc #'doc)
       (catch Exception ex nil)))

init-source should be called during your library initialization.