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.
Reloading Code
While Clojure’s and CIDER’s interactive programming style means you’ll restart your application far less often than with other languages and development environments, sometimes you’ll want to clean everything up and reload one or more namespaces to ensure that they are up to date and there are no temporary definitions hanging around.
Typing C-c M-n r or C-c M-n M-r will invoke
cider-ns-refresh
and reload all modified Clojure files on the
classpath.
Adding a prefix argument, C-u C-c M-n r, will reload all the namespaces on the classpath unconditionally, regardless of their modification status.
Adding a double prefix argument, C-u C-u M-n r, will first clear the state of the namespace tracker before reloading. This is useful for recovering from some classes of error that normal reloads would otherwise not recover from. A good example is circular dependencies. The trade-off is that stale code from any deleted files may not be completely unloaded.
cider-ns-refresh
wraps
clojure.tools.namespace, and as
such the same
benefits
and
caveats
regarding writing reloadable code also apply.
The above three operations are analogous to
clojure.tools.namespace.repl/refresh
,
clojure.tools.namespace.repl/refresh-all
and
clojure.tools.namespace.repl/clear
(followed by a normal refresh), respectively.
You can define Clojure functions to be called before reloading, and after a
successful reload, when using cider-ns-refresh
:
(setq cider-ns-refresh-before-fn "user/stop-system!"
cider-ns-refresh-after-fn "user/start-system!")
These must be set to the namespace-qualified names of vars bound to functions of no arguments. The functions must be synchronous (blocking), and are expected to be side-effecting - they will always be executed serially, without retries.
By default, messages regarding the status of the in-progress reload
will be displayed in the echo area after you call
cider-ns-refresh
. The same information will also be recorded in the
*cider-ns-refresh-log*
buffer, along with anything printed to
*out*
or *err*
by cider-ns-refresh-before-fn
and
cider-ns-refresh-start-fn
.
You can make the *cider-ns-refresh-log*
buffer display automatically
after you call cider-ns-refresh
by setting the
cider-ns-refresh-show-log-buffer
variable to a non-nil value. This
will also prevent any related messages from also being displayed in
the echo area.
(setq cider-ns-refresh-show-log-buffer t)
By default, CIDER will prompt for whether to save all modified clojure-mode
buffers visiting files on the classpath. You can customize this behavior with
cider-ns-save-files-on-refresh
and cider-ns-save-files-on-refresh-modes
.
Sometimes, cider-ns-refresh
may not work for you. If you’re looking
for a bit more forceful reloading the cider-ns-reload
and cider-ns-reload-all
commands can be used instead. These commands
invoke Clojure’s (require ... :reload)
and (require
... :reload-all)
commands at the REPL.
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 |
|
p |
|
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.
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
.
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. |
n |
Go to next line. |
p |
Go to previous line. |
Browsing the Clojure Spec Registry
If you are using Clojure 1.9 or newer you can browse 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.
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.