CIDER comes with a powerful REPL, which is quite handy when you want to experiment with the code you're working on or just explore some stuff (e.g. a library you're playing with). The REPL offers a number of advanced features:
- auto-completion
- font-locking (the same as in
clojure-mode
) - quick access to many CIDER commands (e.g. definition and documentation lookup, tracing, etc)
Here's a list of the keybindings that are available in CIDER's REPL:
Keyboard shortcut | Description |
---|---|
RET | Evaluate the current input in Clojure if it is complete. If incomplete, open a new line and indent. If invoked with a prefix argument is given then the input is evaluated without checking for completeness. |
C-RET | Close any unmatched parenthesis and then evaluate the current input in Clojure. |
C-j | Open a new line and indent. |
C-c C-o | Remove the output of the previous evaluation from the REPL buffer. With a prefix argument it will clear the entire REPL buffer, leaving only a prompt. |
C-c M-o | Switch between the Clojure and ClojureScript REPLs for the current project. |
C-c C-u | Kill all text from the prompt to the current point. |
C-c C-b C-c C-c |
Interrupt any pending evaluations. |
C-up C-down |
Go to to previous/next input in history. |
M-p M-n |
Search the previous/next item in history using the current input as search pattern. If M-p/M-n is typed two times in a row, the second invocation uses the same search pattern (even if the current input has changed). |
M-s M-r |
Search forward/reverse through command history with regex. |
C-c C-n C-c C-p |
Move between the current and previous prompts in the REPL buffer. Pressing RET on a line with old input copies that line to the newest prompt. |
C-c C-x | Reload all modified files on the classpath. |
C-u C-c C-x | Reload all files on the classpath. |
TAB | Complete symbol at point. |
C-c C-d d C-c C-d C-d |
Display doc string for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol |
C-c C-d j C-c C-d C-j |
Display JavaDoc (in your default browser) for the symbol at point. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. |
C-c C-d r C-c C-d C-r |
Lookup symbol in Grimoire. |
C-c C-d a C-c C-d C-a |
Apropos search for functions/vars. |
C-c C-d f C-c C-d C-f |
Apropos search for documentation. |
C-c C-z | Switch to the previous Clojure buffer. This complements C-c C-z used in cider-mode. |
C-c M-i | Inspect expression. Will act on expression at point if present. |
C-c M-n | Select a namespace and switch to it. |
C-c C-. | Jump to some namespace on the classpath. |
C-c M-t v | Toggle var tracing. |
C-c M-t n | Toggle namespace tracing. |
C-c C-t t C-c C-t C-t |
Run test at point. |
C-c C-t g C-c C-t C-g |
Re-run the last test you ran. |
C-c C-t n C-c C-t C-n |
Run tests for current namespace. |
C-c C-t l C-c C-t C-l |
Run tests for all loaded namespaces. |
C-c C-t p C-c C-t C-p |
Run tests for all project namespaces. This loads the additional namespaces. |
C-c C-t r C-c C-t C-r |
Re-run test failures/errors. |
C-c C-t b C-c C-t C-b |
Show the test report buffer. |
C-c C-q | Quit the current nREPL connection. With a prefix argument it will quit all connections. |
There's no need to memorize this list. In any REPL buffer you'll have a REPL
menu available, which lists all the most important commands and their
keybindings. You can also invoke C-h f RET cider-repl-mode
to get a list of the
keybindings for cider-repl-mode
.
In the REPL you can also use "shortcut commands" by pressing ,
at the
beginning of a REPL line. You'll be presented with a list of commands you can
quickly run (like quitting, displaying some info, clearing the REPL, etc). The
character used to trigger the shortcuts is configurable via
cider-repl-shortcut-dispatch-char
. Here's how you can change it to ;
:
(setq cider-repl-shortcut-dispatch-char ?\;)
REPL Configuration
Behavior on connect
Normally, the REPL buffer is auto-displayed in a separate window after a connection is established. You can suppress this behaviour like this:
(setq cider-repl-pop-to-buffer-on-connect nil)
Behavior on switch
By default C-c C-z will display the REPL buffer in a different window. You can make C-c C-z switch to the CIDER REPL buffer in the current window:
(setq cider-repl-display-in-current-window t)
Eldoc
Eldoc displays function signatures in the minibuffer as you're typing.
It's extremely useful! Enable eldoc
in REPL buffers like this:
(add-hook 'cider-repl-mode-hook #'eldoc-mode)
Customizing the REPL prompt
You can customize the prompt in REPL buffer. To do that you can customize
cider-repl-prompt-function
and set it to a function that takes one argument,
a namespace name. For convenience, three functions are already provided:
cider-repl-prompt-lastname
, cider-repl-prompt-abbreviated
,
cider-repl-prompt-default
and by default the last one is being used.
Prompt for each of them for namespace leiningen.core.ssl
:
cider-repl-prompt-lastname
:
ssl>
cider-repl-prompt-abbreviated
:
l.c.ssl>
cider-repl-prompt-default
:
leiningen.core.ssl>
You may, of course, write your own function. For example, in leiningen
there
are two namespaces with similar names - leiningen.classpath
and
leiningen.core.classpath
. To make them easily recognizable you can either
use the default value or you can opt to show only two segments of the
namespace and still be able to know which is the REPL's current
namespace. Here is an example function that will do exactly that:
(defun cider-repl-prompt-show-two (namespace)
"Return a prompt string with the last 2 segments of NAMESPACE."
(let ((names (reverse (subseq (reverse (split-string namespace "\\.")) 0 2))))
(concat (car names) "." (cadr names) "> ")))
TAB Completion
You can control the TAB key behavior in the REPL via the
cider-repl-tab-command
variable. While the default command
cider-repl-indent-and-complete-symbol
should be an adequate choice for
most users, it's very easy to switch to another command if you wish
to. For instance if you'd like TAB to only indent (maybe
because you're used to completing with M-TAB) use the
following snippet:
(setq cider-repl-tab-command #'indent-for-tab-command)
Result Prefix
Change the result prefix for REPL evaluation (by default there's no prefix):
(setq cider-repl-result-prefix ";; => ")
And here's the result of that change:
user> (+ 1 2)
;; => 3
Customize the REPL Buffer's Name
The REPL buffer name has the format *cider-repl project-name*
.
You can change the separator from space to something else by overriding nrepl-buffer-name-separator
.
(setq nrepl-buffer-name-separator "-")
The REPL buffer name can also display the port on which the nREPL server is running.
Buffer name will look like *cider-repl project-name:port*
.
(setq nrepl-buffer-name-show-port t)
Font-locking
Normally code in the REPL is font-locked the same way as in
clojure-mode
. Before CIDER 0.10 by default REPL input was font-locked with
cider-repl-input-face
(after you press RET
) and results were font-locked with
cider-repl-result-face
. If you want to restore the old behaviour use:
(setq cider-repl-use-clojure-font-lock nil)
Pretty printing in the REPL
Make the REPL always pretty-print the results of your commands.
M-x cider-repl-toggle-pretty-printing
Limiting printed output in the REPL
Accidentally printing large objects can be detrimental to your
productivity. Clojure provides the *print-length*
var which, if set,
controls how many items of each collection the printer will print. You
can supply a default value for REPL sessions via the repl-options
section of your Leiningen project's configuration.
:repl-options {:init (set! *print-length* 50)}
REPL history
- To make the REPL history wrap around when its end is reached:
(setq cider-repl-wrap-history t)
- To adjust the maximum number of items kept in the REPL history:
(setq cider-repl-history-size 1000) ; the default is 500
- To store the REPL history in a file:
(setq cider-repl-history-file "path/to/file")
Note that the history is written to the file when you kill the REPL
buffer (which includes invoking cider-quit
) or you quit Emacs.