Compliment

Compliment is a fast and smart completion library for Clojure. It can complete vars, namespaces, classes, class members, keywords, locals. Users and library authors can also extend Compliment with custom completion sources.

Compliment is used as a completion backend in the following editors/IDEs:

• Emacs — CIDER
• Vim — vim-fireplace
• Visual Studio Code — Calva
• rebel-readline

Most importantly, I am very glad you came here. You look gorgeous today.

Rationale

I wrote Compliment specifically for you because you are amazing and I believe you deserve a matching completion lib. Here are the features it boasts:

• Speed. Your time is too precious to wait for completion to happen. Compliment is designed to be fast and is carefully benchmarked to make sure no sudden performance drops appear.
• Smart completion. Such a smart person like you is entitled to completion being smart as well. Default Compliment sources use various techniques to give more meaningful completion depending on the context, and allow some fuzziness in prefix.
• Extensibility. Your insatiable passion for exploration won't be satisfied by a set in stone completion list. For this reason Compliment allows every library developer to write custom sources, so later other users of the library will have better experience utilizing it.

Installation

In most Clojure IDEs that use Compliment, you don't have to install anything at all — it will already be there for you. In case you are a CIDER user you'll also need to install company-mode and company-quickhelp for optimal results. This guide will help you configure it.

To embed Compliment directly into your program add this to the :dependencies:

If you don't want to pull a dependency, check Compliment-lite.

For users

Here are the examples of different completion scenarios Compliment supports.

You can advise Compliment to provide special treatment for certain Vars by attaching metadata to them. See the Metadata page for details.

For developers

Compliment's primary public function is completions:

=> (require 'compliment.core)
=> (compliment.core/completions "compl")
({:candidate "complement", :type :function, :ns "clojure.core"}
 {:candidate "completing", :type :function, :ns "clojure.core"}
 {:candidate "compliment.core", :type :namespace, :file "compliment/core.clj"}
 {:candidate "compliment.utils", :type :namespace, :file "compliment/utils.clj"}
 ...)

completions can accept a map of options as a second argument. The supported options are:

• :ns — complete within the provided namespace
• :context — enable richer completions, see Context.
• :sort-order — how to sort resulting candidates, either :by-length (default) or :by-name.
• :extra-metadata — a list of keywords for extra metadata to attach to each candidate. Only used for completing vars. The values can be :doc, :arglists, :deprecated, :private.
• :sources — a list of sources names that should be used when generating candidates. The name of the source is a keyword passed to defsource in each source namespace. If not provided, all sources will be used.

The second public function is documentation. It can be used for generating tooltip messages when the completion candidate is highlighted in the UI:

=> (println (compliment.core/documentation ".substring"))

java.lang.StringBuilder.substring
  (int int) -> String (public volatile)
  (int) -> String (public volatile)

java.lang.StringBuffer.substring
  (int int) -> String (public synchronized)
  (int) -> String (public synchronized)

java.lang.String.substring
  (int int) -> String (public)
  (int) -> String (public)

See tests for more examples and details.

Writing your own sources is explained in Custom sources.

License

Copyright © 2013-2024 Oleksandr Yakushev. Distributed under the Eclipse Public License. See LICENSE.