CIDER (formerly nrepl.el) is the Clojure IDE and REPL for Emacs, built on top of nREPL, the Clojure networked REPL server. It's a great alternative to the now deprecated combination of SLIME + swank-clojure.
You'll need to have Emacs installed (preferably the latest stable release). If you're new to Emacs you might want to read this tutorial, dedicated to setting up Emacs for Clojure development, first.
Before installing CIDER make sure you've removed the old nrepl.el package and all packages that depend on it. Use only packages updated to work with CIDER!
You'll also need to adjust your config accordingly, as most settings were renamed in CIDER. Consult the Configuration section of the README for more details.
package.el is the built-in package manager in Emacs.
CIDER is available on both major package.el community maintained repos - Marmalade and MELPA.
If you're not already using one of them, follow their installation instructions: Marmalade, MELPA.
You can install CIDER with the following command:
M-x package-install [RET] cider [RET]
or by adding this bit of Emacs Lisp code to your Emacs initialization file(.emacs or init.el):
(unless (package-installed-p 'cider) (package-install 'cider))
If the installation doesn't work try refreshing the package list:
M-x package-refresh-contents [RET]
Keep in mind that MELPA packages are built automatically from the master branch, meaning bugs might creep in there from time to time. Never-the-less, installing from MELPA is the recommended way of obtaining CIDER, as the master branch is normally quite stable and "stable" (tagged) builds are released somewhat infrequently.
el-get is another popular package manager for Emacs. If you're an el-get user just do M-x el-get-install.
You can install CIDER manually by placing CIDER on your load-path and requireing it. Many people favour the folder ~/.emacs.d/vendor:
(add-to-list 'load-path "~/emacs.d/vendor") (require 'cider)
Keep in mind that CIDER depends on clojure-mode, dash.el and pkg-info so you'll have to install them as well.
CIDER comes bundled in Emacs Prelude. If you're a Prelude user you can start using it right away.
CIDER comes bundled in Emacs Live. If you're using Emacs Live you're already good to go.
Some of CIDER's functionality (like the inspector, ClojureScript completion, etc) depends on the presence of CIDER's own nREPL middleware.
Other functionality will work out of the box, but will be enhanced in the presence of the extra middleware. All CIDER users are encouraged to use it.
You can certainly use CIDER without configuring it any further, but here are some ways other folks are adjusting their CIDER experience.
eldoc in Clojure buffers:(add-hook 'cider-mode-hook 'cider-turn-on-eldoc-mode)
*nrepl-connection* and *nrepl-server* buffers from appearing in some buffer switching commands like switch-to-buffer(C-x b) like this:(setq nrepl-hide-special-buffers t)
When using switch-to-buffer, pressing SPC after the command will make the hidden buffers visible. They'll always be visible in list-buffers (C-x C-b).
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)
(setq cider-repl-pop-to-buffer-on-connect nil)
(setq cider-popup-stacktraces nil)
(setq cider-repl-popup-stacktraces t)
(setq cider-auto-select-error-buffer t)
*cider-repl project-name*. Change the separator from space to something else by overriding nrepl-buffer-name-separator.(setq nrepl-buffer-name-separator "-")
(setq nrepl-buffer-name-show-port t)
(setq cider-repl-display-in-current-window t)
(setq cider-repl-print-length 100) ; the default is nil, no limit
(setq cider-prompt-save-file-on-load nil)
(set cider-repl-result-prefix ";; => ")
And here's the result of that change:
=> ):(set cider-interactive-eval-result-prefix ";; => ")
To remove the prefix altogether just set it to an empty string("").
cider-repl-input-face (after you press RET) and results are font-locked with cider-repl-output-face. If you want them to be font-locked as in clojure-mode use the following:(setq cider-repl-use-clojure-font-lock t)
cider-switch-to-repl-command variable. While the default command cider-switch-to-relevant-repl-buffer should be an adequate choice for most users, cider-switch-to-current-repl-buffer offers a simpler alternative where CIDER will not attempt to match the correct REPL buffer based on underlying project directories:(setq cider-switch-to-repl-command 'cider-switch-to-current-repl-buffer)
(setq cider-known-endpoints '(("host-a" "10.10.10.1" "7888") ("host-b" "7888")))
(setq cider-repl-wrap-history t)
(setq cider-repl-history-size 1000) ; the default is 500
(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.
Out-of-the box CIDER uses the standard completing-read Emacs mechanism. While it's not fancy it certainly gets the job done (just press TAB). There are, however, ways to improve upon the standard completion if you wish to.
icomplete is bundled with Emacs and enhances the default minubuffer completion:
ido is also bundled with Emacs and offers more features than icomplete. If you are using ido, be sure to use both ido-everywhere and ido-ubiquitous. You might also want to install ido-flex.
CamelCase support for editing commands(like forward-word, backward-word, etc) in the REPL is quite useful since we often have to deal with Java class and method names. The built-in Emacs minor mode subword-mode provides such functionality:(add-hook 'cider-repl-mode-hook 'subword-mode)
clojure-mode buffers (if you're not you probably should). You might also want to enable paredit in the REPL buffer as well:(add-hook 'cider-repl-mode-hook 'paredit-mode)
smartparens in the REPL buffer use the following code:(add-hook 'cider-repl-mode-hook 'smartparens-strict-mode)
(add-hook 'cider-repl-mode-hook 'rainbow-delimiters-mode)
ac-nrepl provides completion source for the popular Emacs interactive auto-completion framework auto-complete. Where nREPL provides it, pop-up documentation for completed symbols will be displayed.
company-cider provides completion back-end with similar functionality for company-mode.
As long as company-mode has the company-capf back-end enabled, it will retrieve completion information from cider-complete-at-point, requiring no additional setup.
The only requirement to use CIDER is to have a nREPL server to which it may connect. Many Clojurians favour the use of the Leiningen tool to start a nREPL server, but the use of Leiningen is not a prerequisite to use CIDER (but it's required if you want to use the cider-jack-in command).
Leiningen is the de facto standard build/project management tool for Clojure. It has a similar scope to the Maven build tool favoured by Java developers (Leiningen actually reuses many things from the Maven ecosystem).
CIDER features a command called cider-jack-in that will start an nREPL server for a particular Leiningen project and connect to it automatically. This functionality depends on Leiningen 2. Older versions are not supported. Follow the installation instructions on Leiningen's web site to get it up and running and afterwards create a project like this:
The two main ways to obtain an nREPL connection are discussed in the following sections of the manual.
Launch a nREPL server and client from EmacsSimply open in Emacs a file belonging to your lein project (like foo.clj) and type M-x cider-jack-in. This will start a nREPL with all the deps loaded in, plus an CIDER client connected to it.
Alternative you can use C-u M-x cider-jack-in to specify the name of a lein project, without having to visit any file in it.
Connect to a running nREPL serverYou can go to your project's dir in a terminal and type there (assuming you're using Leiningen that is):
Alternatively you can start nREPL either manually or by the facilities provided by your project build tool (Maven, etc).
After you get your nREPL server running go back to Emacs. Typing there M-x cider-connect will allow you to connect to the running nREPL server.
Using the cider minor modeCIDER comes with a handy minor mode called cider-mode (complementing clojure-mode) that allows you to evaluate code in your Clojure source files and load it directly in the REPL. A list of all available commands is available in the CIDER menu and in the following section of this manual.
Make the REPL always pretty-print the results of your commands. Note that this will not work correctly with forms such as (def a 1) (def b2) and it expects clojure.pprint to have been required already (the default in more recent versions of Clojure):
M-x cider-repl-toggle-pretty-printing
Limiting printed output in the REPLAccidentally 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 by setting the cider-repl-print-length variable to an integer value. The enforcement of this limit can then be toggled using:
M-x cider-repl-toggle-print-length-limiting
While you're in clojure-mode, cider-jack-in is bound for convenience to C-c M-j and cider-connect is bound to C-c M-c.
macroexpand-1 on the form at point and display the result in a macroexpansion buffer. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1. C-c M-m Invoke clojure.walk/macroexpand-all on the form at point and display the result in a macroexpansion buffer. C-c C-n Eval the ns form. C-c M-n Switch the namespace of the REPL buffer to the namespace of the current buffer. C-c C-z 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. C-u C-u C-c C-z Switch to the REPL buffer based on a user prompt for a directory. C-c M-d Display default REPL connection details, including project directory name, buffer namespace, host and port. C-c M-r Rotate and display the default nREPL connection. C-c M-o Clear the entire REPL buffer, leaving only a prompt. Useful if you're running the REPL buffer in a side by side buffer. C-c C-k Load the current buffer. C-c C-l Load a file. C-c 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-s Display the source 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-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 M-i Inspect expression. Will act on expression at point if present. M-. Jump to the definition of a symbol. If invoked with a prefix argument, or no symbol is found at point, prompt for a symbol. M-, Return to your pre-jump location. M-TAB Complete the symbol at point. 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 M-o Clear the entire REPL buffer, leaving only a prompt. C-c C-o Remove the output of the previous evaluation from the REPL buffer. 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 Goto 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. TAB Complete symbol at point. C-c 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-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-z Switch to the previous Clojure buffer. This complements C-c C-z used in cider-mode. C-c M-f Select a function from the current namespace and insert into the REPL buffer. 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.
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 ?\:)cider-macroexpansion-minor-mode Keyboard shortcut Description C-c C-m Invoke
macroexpand-1 on the form at point and replace the original form with its expansion. If invoked with a prefix argument, macroexpand is used instead of macroexpand-1. C-c M-m Invoke clojure.walk/macroexpand-all on the form at point and replace the original form with its expansion. g The prior macroexpansion is performed again and the current contents of the macroexpansion buffer are replaced with the new expansion. C-/ C-x u Undo the last inplace expansion performed in the macroexpansion buffer. Keyboard shortcut Description Tab and Shift-Tab navigate inspectable sub-objects Return inspect sub-objects l pop to the parent object g refresh the inspector (e.g. if viewing an atom/ref/agent) Managing multiple sessions
You can connect to multiple nREPL servers using M-x cider-jack-in multiple times. To close the current nREPL connection, use M-x nrepl-close. M-x cider-quit closes all connections.
CIDER maintains a list of nREPL connections and a single 'default' connection. When you execute CIDER commands in a Clojure editing buffer such as to compile a namespace, these commands are executed against the default connection.
You can display the default nREPL connection using C-c M-d and rotate the default connection using C-c M-r. Another option for setting the default connection is to execute the command M-x nrepl-make-repl-connection-default in the appropriate REPL buffer.
To switch to the relevant REPL buffer based on the Clojure namespace in the current Clojure buffer, use: C-c C-z. You can then use the same key combination to switch back to the Clojure buffer you came from.
The single prefix C-u C-c C-z, will switch you to the relevant REPL buffer and set the namespace in that buffer based on namespace in the current Clojure buffer.
To explicitly choose the REPL buffer that C-c C-z uses based on project directory, use a double prefix C-u C-u C-c C-z. This assumes you have cider-switch-to-relevant-repl mapped to the var cider-switch-to-repl-command which is the default configuration.
To change the designation used for CIDER buffers use M-x cider-change-buffers-designation. This changes the CIDER REPL buffer, nREPL connection buffer and nREPL server buffer. For example using cider-change-buffers-designation with the string "foo" would change *cider-repl localhost* to *cider-repl foo*.
The built-in completion logic in CIDER relies on the library clojure-complete, so you'll have to have it your classpath for completion to work. If you're connecting to an nREPL server started from lein (e.g. you invoked M-x cider-jack-in) - there's nothing for you to do. This is, however, an issue if you're embedding nREPL in an application for instance, because nREPL itself does not depend on clojure-complete.
Note that if you're using an nREPL middleware providing a complete op, CIDER will use it instead of its built-in completion.
ClojureScript completion is provided by the cider-nrepl 'complete' implementation middleware which relies on piggieback. Include it in your project middlewares and call (cemerick.piggieback/cljs-repl) or another method to start up the cljs REPL.
On Microsoft Windows the JVM default line separator string is \r\n which can appear in Emacs as ^M characters at the end of lines printed out by the JVM. One option is to set the buffer-display-table to not show these characters as detailed here (changing slime-repl-mode-hook to cider-repl-mode-hook). Alternatively, setting the system property line.separator to \n at JVM startup will stop the carriage return from being printed and will fix output in all cider buffers. To do so add "-Dline.separator=\"\n\"" to :jvm-opts in ~/.lein/profiles.clj.
The powershell inferior shell mode truncates cider repl output when loaded. As a workaround remove
from your Emacs config.
An extensive changelog is available here.
Extensions & Related projectsThere are a couple of CIDER extensions that add some extra functionality to it:
cider-tracing.CIDER's logo was created by @ndr-qef. You can find the logo in various formats here.
The logo is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.
For questions, suggestions and support refer to our official mailing list. Please, don't report issues there, as this makes them harder to track.
Report issues and suggest features and improvements on the GitHub issue tracker. Don't ask questions on the issue tracker - the mailing list is the place for questions.
Patches under any form are always welcome! GitHub pull requests are even better! :-)
Before submitting a patch or a pull request make sure all tests are passing and that your patch is in line with the contribution guidelines.
Consider improving and extending the community wiki.
Running the tests in batch modeInstall cask if you haven't already, then:
$ cd /path/to/cider
$ cask
Run all tests with:
Copyright © 2012-2014 Tim King, Phil Hagelberg, Bozhidar Batsov, Hugo Duncan, Steve Purcell and contributors.
Distributed under the GNU General Public License, version 3
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4