Miscellaneous Features
As the infomercials always say, "But wait, there’s more!" If simultaneous Clojure and ClojureScript REPLs, interactive programming, code completion, stacktrace navigation, test running, and debugging weren’t enough for you, CIDER delivers several additional features.
Using a Scratchpad
CIDER provides a simple way to create a Clojure scratchpad via the
M-x cider-scratch command. This is a great way to play
around with some code without having to create source files or pollute
the REPL buffer and is very similar to Emacs’s own *scratch* buffer.
In the scratchpad, C-j (cider-eval-print-last-sexp) evaluates the
expression before point and prints its value inline, advancing point;
C-u C-j pretty-prints the result instead. cider-scratch-reset
clears the buffer back to its initial state (keeping its session and
eval destination).
Scratchpads and sessions
Each CIDER session gets its own scratchpad, permanently attached to it, so
your evaluations always go to a known session. When you run cider-scratch
from a buffer with a clear session, you land in that session’s scratchpad
(named *cider-scratch: SESSION*); when the context is ambiguous (or with
a prefix argument), CIDER prompts you to pick one. With no connections at
all, you get a single, session-less *cider-scratch* buffer. Use
cider-scratch-set-session to re-attach a scratchpad to a different session.
Because a scratchpad has no file extension to dispatch on, you choose where
its evaluations go. By default it follows cider-clojurec-eval-destination
(like a .cljc file, i.e. both Clojure and ClojureScript REPLs of its
session). C-c C-M-d (cider-cycle-eval-destination) cycles between
clj, cljs, multi, and auto (infer from the major mode), and the
current choice is shown in the mode line (e.g. [multi]). You can also set it
directly via cider-set-eval-destination or the mode menu.
cider-set-eval-destination and cider-cycle-eval-destination work in any
buffer, not just the scratchpad - they are handy in .cljc buffers too, when
you want to pin evaluations to a specific REPL instead of the
cider-clojurec-eval-destination default.
|
Find References
| The functionality is based on ideas from this article. |
There are two ways to use find references in CIDER:
-
cider-xref-fn-refs(C-c C-? r) shows the usages of the function at point in a dedicated buffer -
cider-xref-fn-refs-select(C-c C-? C-r) shows the usages in the minibuffer
Here’s how they look in action:
Keep in mind the following limitations:
-
This works only for Clojure
-
It’s powered by runtime state analysis, which means it will show only data for loaded namespaces (like most of CIDER’s functionality)
-
It doesn’t (currently) find usages in lambdas
-
It doesn’t give us the precise locations where something is used, we only know that it’s used
On the bright side:
-
It’s super fast
-
It doesn’t require any static code analysis
-
It’s still more reliable than
grep
The functionality is not perfect, but at least it’s there if you need it. As a bonus you get a quick way to navigate to
all of the functions used by some function using cider-xref-fn-deps (C-c C-? d) and cider-xref-fn-deps-select (C-c C-? C-d).
Those are pretty handy if you don’t want to jump to the source of some function to see what functions it refers to (uses) internally.
Searching the project source
The runtime analysis only sees namespaces that have been loaded into the REPL,
and each reference it reports points at the referring function’s definition
rather than the exact call site. To also cover code that hasn’t been evaluated
yet, CIDER can search the project’s source files on disk. It uses the
lightweight info/lookup op (a single, cheap round-trip) to resolve the
symbol at point to its canonical namespace and name, then scans the project’s
files with a Clojure-aware text search, taking each file’s namespace aliases and
:refers into account and pinpointing every occurrence.
cider-xref-fn-refs-in-source (C-c C-? s) runs this search directly and
shows the results in the standard xref buffer. When no REPL is connected it
falls back to matching the bare name, which is less precise but still useful.
By default, xref-find-references (M-?) uses this source search, since it
reports the exact occurrences across the whole project, including code that
hasn’t been loaded. The cider-xref-references-mode variable lets you fold in
the runtime references too:
;; source matches only (the default)
(setq cider-xref-references-mode 'source)
;; runtime references only (the historical behavior)
(setq cider-xref-references-mode 'runtime)
;; both, combined
(setq cider-xref-references-mode 'both)The two answer slightly different questions: the source search finds every
occurrence (in any Clojure dialect), while the runtime search reports the
calling functions (each hit points at the caller’s definition rather than the
call site) and is limited to Clojure on the JVM and to loaded project
namespaces. In both mode the source matches lead, and runtime hits for files
the source search already scanned are dropped, so a loaded reference isn’t
reported twice at two different granularities; what survives is mainly
references the compiler generated from macros, which leave no textual trace.
Because the source search is textual, it’s a smart heuristic rather than a
resolved index. It only looks at the project’s own source files, so it won’t
find references that live in dependencies. It can include false positives such
as shadowing locals or a same-named var referred from a different namespace, and
it can miss references hidden in .cljc reader-conditional branches or built
from strings at runtime. A faster search program helps on large projects; set
xref-search-program to ripgrep if you have it installed.
Don’t forget you also have a couple of third-party alternatives:
-
The much more sophisticated AST-powered "find usages" provided by
clj-refactor.el -
Projectile’s "grep in project" (
projectile-grep, typically bound to C-c p g)
Browsing the call graph
The flat commands above answer "who uses this, right here". To explore further - "who calls the callers, and who calls them" - CIDER offers two SLIME-style browsers that present the same runtime data as an interactive tree:
-
cider-who-calls(C-c C-w c) shows the callers of the function at point -
cider-who-is-called(C-c C-w d) shows what the function at point calls
Each node can be expanded with TAB to reveal the next level of the graph, so you walk it one step at a time rather than computing the whole thing up front; every level is a single round trip, taken only when you ask for it. n and p move between nodes, RET (or .) jumps to a node’s definition, and a function that calls back onto its own path is shown as a leaf so expansion can’t loop forever.
|
Like the flat |
Macros are a special case: they’re expanded away at compile time, so the runtime
ops never see their call sites and cider-who-calls comes up empty for them.
cider-who-macroexpands (C-c C-w m) finds a macro’s use sites by searching
the project’s source instead (the same mechanism as
cider-xref-fn-refs-in-source).
cider-who-implements (C-c C-w i) goes the other way around: point it at a
protocol and it lists the types that implement it; point it at a multimethod and
it lists its methods, all on the same expandable tree. With a recent enough
cider-nrepl it covers inline defrecord/deftype implementers too and jumps
straight to each implementation’s source. For a multimethod, each method jumps to
its defmethod - found by searching the project’s source, since the method
functions themselves carry no source metadata at runtime.
|
When the |
Two more protocol-oriented commands round out the family. cider-type-protocols
(C-c C-w t) is the reverse of cider-who-implements: point it at a type
(a record or class) and it lists the protocols that type implements, including
inline defrecord/deftype implementations. cider-protocols-with-method
(C-c C-w p) takes a method name (by default the one at point) and lists the
protocols that declare it - handy when you spot a bare method call and want to
know which protocol it belongs to. Both jump to the matching protocol’s
definition, and both see loaded Clojure-on-the-JVM code only. With a recent
enough cider-nrepl they use a dedicated middleware op; otherwise they fall back
to a client-side query that works against any nREPL.
The call-graph bindings are also available under the C-c C-? xref prefix, as C-c C-? R and C-c C-? D.
CIDER Selector
The cider-selector (C-c M-s) command allows you to quickly navigate to
important buffers in the context of a Clojure project - e.g. the REPL, the
stacktrace buffer, the doc buffer, the most recently visited Clojure file, etc.
The usage of the command is extremely simple - after invoking it you need to type a
single key identifying the target buffer (e.g. r for the REPL).
|
One thing to keep in mind about the default keybinding C-c M-s is that it’s available only
in buffers where |
Here’s a list of all of cider-selector's keybindings:
| Keyboard shortcut | Description |
|---|---|
c |
Most recently visited Clojure buffer. |
e |
Most recently visited Emacs Lisp buffer. |
r |
Current REPL buffer or most recently visited REPL buffer. |
m |
|
x |
|
d |
|
s |
|
q |
Abort. |
? |
Show help. |
|
Any of those keys can be prefixed with a |
You can easily extend the selector with new commands using def-cider-selector-method:
(def-cider-selector-method ?z
"CIDER foo buffer."
cider-foo-buffer)Browsing the Classpath
You can easily browse the items on your classpath with the command
M-x cider-classpath.
Here you can see it in action:
Press RET on a classpath entry to navigate into it. You can also
jump straight to a classpath entry, selected via completion, with
M-x cider-open-classpath-entry.
Browsing Namespaces
You can browse the contents of any loaded namespace with the command
M-x cider-browse-ns. CIDER will prompt you for the namespace
to browse.
You can also browse all available namespaces with M-x
cider-browse-ns-all.
The contents are shown as a navigable tree: when you group them (see below)
each group is a foldable node you can collapse with TAB. The header
contains buttons which let you control how the buffer is displayed (see below
for keybindings). You may also configure the cider-browse-ns-default-filters
variable to a list of the element types you want to be hidden by default.
There are a bunch of useful keybindings that are defined in browser buffers.
| Keyboard shortcut | Description |
|---|---|
d |
Display documentation for item at point. |
RET |
Browse ns or display documentation for item at point. |
s |
Go to definition for item at point. |
^ |
Browse all namespaces. |
a |
Toggle showing all items (ignore active filters). |
n |
Go to the next node. |
TAB |
Fold or unfold the group at point. |
h p |
Toggle visibility of private items. |
h t |
Toggle visibility of tests. |
h m |
Toggle visibility of macros. |
h f |
Toggle visibility of functions. |
h v |
Toggle visibility of vars. |
g t |
Group items by type (function, macro, var, etc.). |
g v |
Group items by visibility (public vs. private). |
p |
Go to the previous node. |
Browsing the Clojure Spec Registry
If you already know which spec you’re looking for, you can type
M-x cider-browse-spec and CIDER will prompt you for a
spec name and then drop you into the spec browser.
If you aren’t quite sure which spec you want, you can type
M-x cider-browse-spec-all. CIDER will then prompt you for
a regex and will filter out all the spec names that don’t match.
To explore how a spec is composed, M-x cider-browse-spec-tree shows the
spec and the specs it references as an expandable tree: TAB on a node
reveals the namespaced specs that spec depends on (fetched a level at a time),
and RET opens that spec’s full definition in the regular browser. A spec
that recurs onto its own path is shown as a leaf, so the tree never loops.
Once in the browser you can use your mouse or the keybindings below to navigate deeper.
| Keyboard shortcut | Description |
|---|---|
RET |
Browse the spec at point. |
^ |
Go up in the navigation stack. |
n |
Go to next spec. |
p |
Go to previous spec. |
e |
Generate an example for the current browser spec. |
If your project includes the org.clojure/test.check library, you can
type e when browsing a spec to generate an example that
meets the spec.
Clojure Spec Versions
Clojure Spec has a bit of a history and is available in a couple of flavours:
-
spec(akaclojure.spec, the original release, never shipped with Clojure) -
spec-alpha(akaclojure.spec.alpha, the original release under a different name, ships with Clojure) -
spec-alpha-2(akaclojure.alpha.spec, the evolution, separate library, but still experimental)
Cider supports the whole mix, but with a twist.
-
When Cider shows a list of specs, the keys from all registries are shown. Registries are merged together from newest to oldest.
-
When Cider operates on a spec, like looking up a spec or generating data for it, the operation is tried against all registries, from newest to oldest, with the first successful operation winning.
Formatting Code with cljfmt
While CIDER has its own code formatting (indentation) engine, you can also
use it together with cljfmt - that’s useful if you’re working on a team
that uses different editors and IDEs.
CIDER provides several commands to interact with cljfmt:
-
cider-format-defun -
cider-format-region -
cider-format-buffer
Generally it’s a good idea to add some hook like this one to make sure on each save operation your buffers are properly formatted:
(add-hook 'before-save-hook 'cider-format-buffer t t)Notice that you want to apply cljfmt prior to saving the buffer in question.
You can supply additional configuration to cljfmt via the configuration variable
cider-format-code-options. Here’s an example:
;; Let's assume you want to pass the following config
;;
;; {:indents {org.me/foo [[:inner 0]]}
;; :alias-map {\"me\" \"org.me\"}}
;;
;; You'll need to encode it as an Emacs Lisp plist:
(setq cider-format-code-options
'(("indents" (("org.me/foo" (("inner" 0)))))
("alias-map" (("me" "org.me")))))
CIDER doesn’t shell out to cljfmt - it interacts with it via nREPL
(there’s format middleware in cider-nrepl), which is faster than
shelling out.
|
Formatting EDN
Similarly to the cljfmt integration, CIDER also provides a convenient interface
to format EDN using clojure.tools.reader.edn. The following commands are provided:
-
cider-format-edn-last-sexp -
cider-format-edn-region -
cider-format-edn-buffer
Xref integration
Beginning with version 1.2.0, CIDER supports Emacs’s built-in xref
functionality, which means M-. will invoke xref-find-definitions instead of
CIDER’s own command cider-find-var. You can disable the use of CIDER’s xref backend like this:
(setq cider-use-xref nil)
You’ll have to disable and enable cider-mode for this setting to have effect.
|
If you use other packages that also integrate with xref (e.g. lsp-mode), you may wish to customize the precedence of CIDER’s xref backend. The precedence is controlled by the
order in which backend functions appear in the xref-backend-functions hook. By default, the CIDER xref function will be added with a depth of -90, so it will (should?) come first.
If you would prefer for it to have a lower precedence, you can change cider-xref-fn-depth:
(setq cider-xref-fn-depth 90)| See Setting Hooks for more information about depth. |
Cheatsheet
There are two ways to access Clojure cheatsheet in CIDER.
The first one is available through cider-cheatsheet command and displays the cheatsheet in a popup buffer. This is how it looks with two windows displaying the cheatsheet buffer side by side:
The second way is available through cider-cheatsheet-select command, which uses completions in the minibuffer to find a var in the cheatsheet. By default, it provides a multi-step selection process where you need to go section by section until you find a var. This is how it looks in the minibuffer:
By using a prefix argument when calling cider-cheatsheet-select, we can change the behavior of cider-cheatsheet-select so each candidate is represented as a full path to a var. This can be useful with fuzzy completion style and vertical candidates display, as in that case, we can search in any element of the path, possibly getting matches from multiple categories at the same time. This is how it looks with such a workflow:
It is possible to control which function is used on a var when it is selected by customizing cider-cheatsheet-default-action-function. By default, documentation for a var is displayed using cider-doc-lookup, but it can also be set to cider-clojuredocs-lookup to show documentation from ClojureDocs or any other function accepting a var as an argument.
By default the cheatsheet buffer is selected when it pops up (per
cider-auto-select-buffer, which governs all of CIDER’s popup buffers).
Remove cheatsheet from that option’s list form (or set the obsolete
cider-cheatsheet-auto-select-buffer to nil) if you’d rather keep focus in
the current buffer.