Code Evaluation

Code evaluation is at the heart of interactive programming. CIDER provides a ton of evaluation-related commands that can cover just about any use-case one can possibly imagine.

All evaluation commands are defined in cider-eval.el.

Terminology

CIDER’s evaluation commands use a terminology that’s popular within Emacs, but somewhat confusing to people not familiar with it. Let’s take a look at it:

  • defun - top-level expression

  • sexp - s-expression, form

  • last-sexp - the form preceding the cursor (point in Emacs lingo)

  • sexp-at-point - the form under/around the cursor

  • buffer - the abstraction used by Emacs to represent any content; most often backed by a file.

  • region - the selected part of a buffer

  • load - a synonym for "evaluate"; most often used in the context of buffers/files

Basic Evaluation

As CIDER derives almost all of its functionality by inspecting the runtime (REPL) state of your application, you need to evaluate something before functionality like code completion, eldoc or definition lookup would work.

Typically the first think you’d do when visiting a Clojure buffer would be to load (evaluate) the buffer with cider-load-buffer (C-c C-k).

Afterwards most of the time you’d be evaluating expressions one at a time either using cider-eval-last-sexp (C-c C-e or C-x C-e) or cider-eval-defun-at-point (C-c C-c or C-M-x).

What happens if I don’t evaluate the entire buffer first?

You might be wondering why do you need to evaluate the entire source buffer. After all, won’t be it be nice if you could just start evaluating only the forms you’re interested in?

Technically speaking you’re not required to evaluate the entire source buffer first, but not doing so introduces some subtleties and a bit of complexity. In general the only part that’s really essential for subsequent code evaluations is the ns declaration. As expressions within the buffer are evaluated in the context of its namespace and you have to create that namespace first.

In the early days of CIDER, when a namespace didn’t exist CIDER would just throw an error. A lot of people were confused by this behavior and unhappy about it. Eventually CIDER became smarter and now it always knows whether the ns form in some source buffer has been evaluated or changed after it was originally evaluated. With that knowledge in hand CIDER will auto-eval ns forms that were changed prior to evaluating code in that namespace, if you don’t evaluate them yourselves. That behavior is controlled via the variable cider-auto-track-ns-form-changes.

Typically this type of evaluation commands would provide you with dual feedback - you’d see the results in both the Emacs minibuffer and in an inline overlay in the source buffer.

Exotic Evaluation Commands

WIP

Evaluating Clojure Code in the Minibuffer

You can evaluate Clojure code in the minibuffer at almost any time using M-x cider-read-and-eval (bound in cider-mode buffers to C-c M-:). TAB completion will work in the minibuffer, just as in REPL and source buffers.

Typing C-c C-v . in a Clojure buffer will insert the defun at point into the minibuffer for evaluation. This way you can pass arguments to the function and evaluate it and see the result in the minibuffer.

You can also enable other convenient modes in the minibuffer. For instance, you might want to have both eldoc-mode and paredit-mode available to you:

(add-hook 'eval-expression-minibuffer-setup-hook #'eldoc-mode)
(add-hook 'eval-expression-minibuffer-setup-hook #'paredit-mode)

Evaluation Hooks

WIP

Configuration

Overlays

When you evaluate code in Clojure files, the result is displayed in the buffer itself, in an overlay right after the evaluated code. If you want this overlay to be font-locked (syntax-highlighted) like Clojure code, set the following variable.

(setq cider-overlays-use-font-lock t)

You can disable overlays entirely (and display results in the echo-area at the bottom) with the cider-use-overlays variable.

(setq cider-use-overlays nil)

By default, result overlays are displayed at the end of the line. You can set the variable cider-result-overlay-position to display results at the end of their respective forms instead. Note that this also affects the position of debugger overlays.

(setq cider-result-overlay-position 'at-point)

Auto-Save Clojure Buffers on Load

Normally, CIDER prompts you to save a modified Clojure buffer when you type C-c C-k (cider-load-buffer). You can change this behavior by adjusting cider-save-file-on-load.

Don’t prompt and don’t save:

(setq cider-save-file-on-load nil)

Just save without prompting:

(setq cider-save-file-on-load t)

Change the Result Prefix for Interactive Evaluation

Change the result prefix for interactive evaluation (not the REPL prefix). By default the prefix is `⇒ `.

(setq cider-eval-result-prefix ";; => ")

To remove the prefix altogether, just set it to the empty string ("").

Keybindings

You might have noticed that CIDER typically has 2-3 different keybindings for many evaluation commands. In case you’ve been wondering "Why?" the answer is pretty simple - legacy. The principle sources of inspiration for CIDER, Emacs and SLIME, provide more or less the same functionality, but use different keybindings. CIDER tried to find a common ground by adopting them both.

On top of this, at some when it became clear that CIDER has set the world record for evaluation command, we’ve introduced a dedicated keymap for all eval commands (that’s everything with the prefix C-c C-v). This leads to funny situations like cider-eval-defun-at-point having 3 keybindings:

  • C-M-x (Emacs style)

  • C-c C-c (SLIME style)

  • C-c C-v (C-)d (CIDER style)

Okay, those are technically 4 keybindings, but who’s counting!

Below is a listing of most keybindings for evaluation commands:

Command Keyboard shortcut Description

cider-eval-last-sexp

C-x C-e
C-c C-e

Evaluate the form preceding point and display the result in the echo area and/or in an buffer overlay (according to cider-use-overlays). If invoked with a prefix argument, insert the result into the current buffer.

cider-eval-last-sexp-and-replace

C-c C-v w

Evaluate the form preceding point and replace it with its result.

cider-eval-last-sexp-to-repl

C-c M-e

Evaluate the form preceding point and output it result to the REPL buffer. If invoked with a prefix argument, takes you to the REPL buffer after being invoked.

cider-insert-last-sexp-in-repl

C-u C-c M-p

Load the form preceding point in the REPL buffer and eval.

cider-pprint-eval-last-sexp

C-c C-v C-f e

Evaluate the form preceding point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment.

cider-pprint-eval-defun-at-point

C-c C-v C-f d

Evaluate the top level form under point and pretty-print the result in a popup buffer. If invoked with a prefix argument, insert the result into the current buffer as a comment.

cider-eval-defun-at-point

C-M-x
C-c C-c

Evaluate the top level form under point and display the result in the echo area.

cider-eval-list-at-point

C-c C-v l
C-c C-v C-l

Evaluate the list around point.

cider-eval-sexp-at-point

C-c C-v v
C-c C-v C-v

Evaluate the form around point.

cider-eval-defun-at-point

C-u C-M-x
C-u C-c C-c

Debug the top level form under point and walk through its evaluation

cider-eval-defun-up-to-point

C-c C-v z

Evaluate the preceding top-level form up to the point.

cider-eval-region

C-c C-v r

Evaluate the region and display the result in the echo area.

cider-interrupt

C-c C-b

Interrupt any pending evaluations.

cider-eval-ns-form

C-c C-v n

Eval the ns form.

cider-load-buffer-and-switch-to-repl-buffer

C-c M-z

Load (eval) the current buffer and switch to the relevant REPL buffer. Use a prefix argument to change the namespace of the REPL buffer to match the currently visited source file.

cider-load-buffer

C-c C-k

Load (eval) the current buffer.

cider-load-file

C-c C-l

Load (eval) a Clojure file.

cider-load-all-files

C-c C-M-l

Load (eval) all Clojure files below a directory.