Code Completion

CIDER provides intelligent code completion for both source buffers (powered by cider-mode) and REPL buffers.

Internally CIDER leverages compliment for Clojure and clj-suitable for ClojureScript. Improvements to the two libraries automatically translate to improvements in CIDER.

Standard completion

Out-of-the box CIDER uses the standard Emacs tooling for code completion. When you press TAB or M-TAB you’ll get completion candidates in a dedicated buffer.

Code Completion

There are two things to keep in mind about the standard completion:

  1. The default keybinding M-TAB is not usable in desktop environments that use it for switching between open applications.

  2. You have to configure TAB to do completion manually by adding this snippet your Emacs config:

(setq tab-always-indent 'complete)

Normally TAB only indents, but now it will also do completion if the code is already properly indented.

Auto-completion

While the standard Emacs tooling works just fine, we suggest that CIDER users consider using company-mode instead. Company can be used for auto-completion in both source code and REPL buffers. To install company-mode:

M-x package-install RET company RET

After installation, you can turn on company-mode globally:

(global-company-mode)

or through mode-specific hooks:

(add-hook 'cider-repl-mode-hook #'company-mode)
(add-hook 'cider-mode-hook #'company-mode)

When company-mode is enabled, it will receive completion information from cider-complete-at-point and requires no additional setup or plugins.

If you’d prefer to trigger completions manually you can add this to your config:

(setq company-idle-delay nil) ; never start completions automatically
(global-set-key (kbd "M-TAB") #'company-complete) ; use M-TAB, a.k.a. C-M-i, as manual trigger

To make TAB complete, without losing the ability to manually indent, you can add this to your config:

(global-set-key (kbd "TAB") #'company-indent-or-complete-common)

Fuzzy candidate matching

By default company-mode will provide completion candidates with the assumption that whatever you’ve typed so far is a prefix of what you’re really trying to type. For example, if you type map- then you’ll only get completion candidates that have map- as the beginning of their names. Sometimes, you don’t know the exact prefix for the item you want to type. In this case, you can get CIDER-specific "fuzzy completion" by adding:

(add-hook 'cider-repl-mode-hook #'cider-company-enable-fuzzy-completion)
(add-hook 'cider-mode-hook #'cider-company-enable-fuzzy-completion)

Now, company-mode will accept certain fuzziness when matching candidates against the prefix. For example, typing mi will show you map-indexed as one of the possible completion candidates and cji will complete to clojure.java.io. Different completion examples are shown here.

Completion annotations

Completion candidates will be annotated by default with an abbreviation corresponding to their type, and (contextually) their namespace. The function used to format the annotation can be configured by cider-annotate-completion-function. The abbreviations used are configured by cider-completion-annotations-alist and the context in which their namespace is included is configured by cider-completion-annotations-include-ns.

Completion Annotations
Completion annotations can be disabled by setting cider-annotate-completion-candidates to nil.

Changing the completion style

Sometimes the user may want to use a different completion style just for the CIDER complete at point function. That can be achieved by setting completion-category-defaults, overriting the completion style of the CIDER complete at point function. The following snippet accomplishes that:

(add-to-list 'completion-category-defaults '(cider (styles basic)))

Updating stale classes and methods cache

Sometimes, the completion fails to recognize new classes that came with dependencies that were loaded dynamically after the REPL was started (e.g. via Boot). Executing M-x cider-completion-flush-caches (or going through the menu CIDER Interaction->Misc->Flush completion cache) forces the completion backend to re-read all classes it can find on the classpath.

Implementation Details

You don’t really need to know any of this if you’re using only cider-jack-in.

The bulk of the code completion logic resides in cider-nrepl completion middleware. Internally it delegates to compliment for the Clojure completion and clj-suitable for the ClojureScript completion.

Starting with nREPL 0.8, there’s also a built-in completions nREPL op that CIDER will fallback to, in the absence of cider-nrepl. Its API is similar to that of the complete op in cider-nrepl and it can be configured to use different completion functions. The built-in op currently supports only Clojure. See the nREPL docs for more details.

Basically, you’ll get great code completion in the presence of cider-nrepl and basic completion otherwise.