Emacs: Clojure CIDER Tutorial

By Xah Lee. Date: . Last updated: .

this page is a tutorial on tool “CIDER”, for working with Clojure in emacs.

Cider home page is at https://github.com/clojure-emacs/cider

emacs Clojure CIDER nrepl
cider-mode's interactive Clojure REPL.

What does CIDER do?

Primarily, CIDER lets emacs eval Clojure code within emacs. When editing Clojure code in clojure-mode, you can eval code expression, a selection, or whole buffer.

CIDER also gives you a interactive Clojure shell inside emacs.

CIDER also lets you view Clojure function's doc in emacs. (like describe-function for emacs lisp, but for Clojure lisp.)

About Emacs

I assume you already have emacs 24.x installed. If not, see: Tutorial: Install Emacs for {Windows, Mac, Linux}

I assume you already know the basics of emacs. Such as how to open file, how to save file. If not, all you have to do is pull menu with mouse. See: Xah Emacs Tutorial.

You should know how to install emacs MELPA packages. See this page for a tutorial: Emacs: How to Install Packages Using ELPA, MELPA, Marmalade.

Install CIDER

you need:

emacs 24.x. (type emacs --version in terminal. Or, in emacs, 【Alt+xversion). I recommend emacs 24.4 or later. See: Tutorial: Install Emacs for {Windows, Mac, Linux}. On Linux, i recommend you compile yourself, it's very easy if you follow this page: How to Build Emacs on Linux.

You need Leiningen. See: Clojure Leiningen Tutorial.

You need clojure-mode. See: Emacs: How to Install Packages Using ELPA, MELPA, Marmalade.

You need cider-mode. See: Emacs: How to Install Packages Using ELPA, MELPA, Marmalade.

Simple Steps to Start Using Cider

① Create a Clojure Project by Leiningen

In terminal, type lein new app xtest. (replace “xtest” by whatever you want to name) This will create a project (a directory) in current directory.

② Add Cider as Dependency to Project

You will have a file at “xtest/project.clj”. In the file, modify the :plugins value, by adding [cider/cider-nrepl "0.7.0"]

Here's a sample file:

(defproject xtest "0.1.0-SNAPSHOT"
  :description "FIXME: testing lein and clojure"
  :url "http://xahlee.info/"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.6.0"]]
  :main ^:skip-aot xtest.core
  :target-path "target/%s"
  :profiles {:uberjar {:aot :all}}
  :plugins [[cider/cider-nrepl "0.7.0"]]
)

Note: the emacs cider-mode version should match the cider/cider-nrepl version in lein's project.clj file. It's tricky to find out exactly which version of cider-mode you are using. But anyway, if you run into a error message warning you about version mismatch, you can try change the plugin to something like this:

[cider/cider-nrepl "0.8.0-SNAPSHOT"]

③ Start Network REPL by lein

in terminal, start the networked repl by lein repl. (cd to your project directory first)

◆ lein repl
nREPL server started on port 35922 on host 127.0.0.1 - nrepl://127.0.0.1:35922
REPL-y 0.3.5, nREPL 0.2.6
Clojure 1.6.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_25-b17
    Docs: (doc function-name-here)
          (find-doc "part-of-name-here")
  Source: (source function-name-here)
 Javadoc: (javadoc java-object-or-class-here)
    Exit: Control+D or (exit) or (quit)
 Results: Stored in vars *1, *2, *3, an exception in *e

user=>

it'll show a IP address and port for nREPL (aka network REPL)

Note: you can start lein repl in emacs using eshell. Just call eshell then type lein repl.

④ Call cider-connect in Emacs

In emacs, call cider-connect

give the IP and port number, shown in the lein repl

emacs Clojure CIDER nrepl
cider-mode's interactive Clojure REPL.

Now, you'll have a Clojure repl running inside emacs.

cider-quitCtrl+c Ctrl+q】 → quit cider repl.

Cider Commands

While in CIDER shell, call describe-mode

cider-repl-mode is an interactive compiled Lisp function in
`cider-repl.el'.

(cider-repl-mode)

Major mode for Clojure REPL interactions.

key             binding
---             -------

C-a             cider-repl-bol
TAB             cider-repl-tab
C-j             cider-repl-newline-and-indent
RET             cider-repl-return
,               cider-repl-handle-shortcut
DEL             backward-delete-char-untabify
C-S-a           cider-repl-bol-mark
C-:             clojure-toggle-keyword-string
<C-down>        cider-repl-forward-input
<C-return>      cider-repl-closing-return
<C-up>          cider-repl-backward-input

C-x C-e         cider-eval-last-sexp

M-,             cider-jump-back
M-.             cider-jump-to-var
M-n             cider-repl-next-input
M-p             cider-repl-previous-input
M-r             cider-repl-previous-matching-input
M-s             cider-repl-next-matching-input

C-c C-b .. C-c C-c              cider-interrupt
C-c C-d         cider-doc-map
C-c RET         cider-macroexpand-1
C-c C-n         cider-repl-next-prompt
C-c C-o         cider-repl-clear-output
C-c C-p         cider-repl-previous-prompt
C-c C-q         cider-quit
C-c C-r         cider-eval-region
C-c C-u         cider-repl-kill-input
C-c C-x         cider-refresh
C-c C-z         cider-switch-to-last-clojure-buffer

C-c C-e         lisp-eval-last-sexp
C-c C-l         clojure-load-file
C-c C-r         lisp-eval-region
  (that binding is currently shadowed by another mode)
C-c C-z         clojure-display-inferior-lisp-buffer
  (that binding is currently shadowed by another mode)

C-x C-e         lisp-eval-last-sexp
  (that binding is currently shadowed by another mode)

C-M-x           lisp-eval-defun

C-M-q           indent-sexp

C-M-q           prog-indent-sexp
  (that binding is currently shadowed by another mode)

C-c M-.         cider-jump-to-resource
C-c M-f         cider-load-fn-into-repl-buffer
C-c M-i         cider-inspect
C-c M-m         cider-macroexpand-all
C-c M-n         cider-repl-set-ns
C-c M-o         cider-repl-clear-buffer
C-c M-s         cider-selector
C-c M-t         cider-toggle-trace

C-c C-d C-a     cider-apropos
C-c C-d C-d     cider-doc
C-c C-d C-g     cider-grimoire
C-c C-d C-j     cider-javadoc
C-c C-d A       cider-apropos-documentation
C-c C-d a       cider-apropos
C-c C-d d       cider-doc
C-c C-d g       cider-grimoire
C-c C-d h       cider-grimoire-web
C-c C-d j       cider-javadoc

C-c M-c         cider-connect
C-c M-j         cider-jack-in

clojure-mode + cider-mode Commands

While in clojure-mode, call cider-eval-last-sexpCtrl+x Ctrl+e】 to evaluate the expression (parenthesis unit) to the left of cursor.

Call cider-doc to see the doc of the symbol under cursor. Or, call universal-argumentCtrl+u】 first, and it'll prompt you to type a function name.

Here's clojure-mode's major command and keys. Note that some keys are overridden by cider-mode.

While in “clojure-mode”, call describe-mode

clojure-mode is an interactive autoloaded compiled Lisp function in
`clojure-mode.el'.

key             binding
---             -------

DEL             backward-delete-char-untabify
C-:             clojure-toggle-keyword-string

C-c C-e         lisp-eval-last-sexp
  (that binding is currently shadowed by another mode)
C-c C-l         clojure-load-file
  (that binding is currently shadowed by another mode)
C-c C-r         lisp-eval-region
  (that binding is currently shadowed by another mode)
C-c C-z         clojure-display-inferior-lisp-buffer
  (that binding is currently shadowed by another mode)
C-c ESC         Prefix Command

C-x C-e         lisp-eval-last-sexp
  (that binding is currently shadowed by another mode)

C-M-x           lisp-eval-defun
  (that binding is currently shadowed by another mode)

C-M-q           indent-sexp

C-M-q           prog-indent-sexp
  (that binding is currently shadowed by another mode)

C-c M-c         cider-connect
C-c M-j         cider-jack-in

For general tips for editing lisp code, see: How to Edit Lisp Code with Emacs