An elisp nREPL client
Emacs Lisp
Pull request Compare This branch is 3354 commits behind clojure-emacs:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
.gitignore
README.md
nrepl.el

README.md

nrepl.el

nrepl.el is an Emacs client for nREPL, the Clojure networked REPL server. It's a great alternative to the now deprecated combination of SLIME + swank-clojure.

Installation

Via package.el

package.el is the built-in package manager in Emacs 24+. On Emacs 23 you will need to get package.el yourself if you wish to use it.

nrepl.el is available on the both Marmalade and MELPA repos.

If you're not already using Marmalade, add this to your ~/.emacs.d/init.el and load it with M-x eval-buffer.

(require 'package)
(add-to-list 'package-archives
             '("marmalade" . "http://marmalade-repo.org/packages/"))
(package-initialize)

For MELPA the code you need to add is:

(require 'package)
(add-to-list 'package-archives
             '("melpa" . "http://melpa.milkbox.net/packages/") t)
(package-initialize)

And then you can install:

M-x package-install [RET] nrepl [RET]

or

(when (not (package-installed-p 'nrepl))
  (package-install 'nrepl))

If installation doesn't work try refreshing package list first:

M-x package-refresh-contents [RET]

Via el-get

el-get is another popular package manager for Emacs. If you're an el-get user just do M-x el-get-install.

Manual

You can install nrepl.el manually by placing nrepl.el on your load-path and requireing it. Many people favour the folder ~/.emacs.d/vendor:

(add-to-list 'load-path "~/emacs.d/vendor")
(require 'nrepl)

Keep in mind that nrepl.el depends on clojure-mode so you'll have to install clojure-mode as well.

Emacs Prelude

nrepl.el is comes bundled with Emacs Prelude. If you're a Prelude user you can start using it right away.

Configuration

You can certainly use nrepl.el without configuring it any further, but here are some ways other folks are adjusting their nrepl.el experience.

  • Enable eldoc in clojure buffers:
(add-hook 'nrepl-interaction-mode-hook
  'nrepl-turn-on-eldoc-mode)
  • Stop the error buffer from popping up while working in the REPL buffer:
(setq nrepl-popup-stacktraces nil)
  • Make C-c C-z switch to the *nrepl* buffer in the current window:
(add-to-list 'same-window-buffer-names "*nrepl*") 
  • The use of paredit when editing Clojure (or any other Lisp) code is highly recommended. You're probably using it already in your clojure-mode buffers (if you're not you probably should). You might also want to enable paredit in the nREPL buffer as well:
(add-hook 'nrepl-mode-hook 'paredit-mode)

Basic Usage

Launch a nrepl server and client from Emacs

Simply open in Emacs a file belonging to your lein project (like foo.clj) and you type M-x nrepl-jack-in. This will start a nREPL with all the deps loaded in, plus an nrepl.el client connected to it.

Alternative you can use C-u M-x nrepl-jack-in to specify the name of a lein project, without having to visit any file in it.

Connect to a running nrepl server

You can go to your project's dir in a terminal and type there:

$ lein repl

Afterwards typing M-x nrepl will allow you to connect to the running nrepl session.

Using the nrepl minor mode

nrepl.el comes with a handy minor mode called nrepl-interaction-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 nREPL menu and in the following section of this manual.

Keys

  • M-x nrepl-jack-in: Launch an nrepl server and a repl client. Prompts for a project root if given a prefix argument.
  • M-x nrepl: Connect to an already-running nrepl server.

Clojure buffer commands:

  • C-x C-e: Evalulate the form preceding point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer.
  • C-M-x: Evaluate the top level form under point and display the result in the echo area. If invoked with a prefix argument, insert the result into the current buffer.
  • C-c C-r: Evaluate the region and display the result in the echo area.
  • C-c C-b: Interrupt any pending evaluations.
  • C-c C-m: Invoke macroexpand-1 on the form preceding point and display result in a macroexpansion buffer. If invoked with a prefix argument, pprint the result.
  • C-c M-m: Invoke clojure.walk/macroexpand-all on the form preceding point and display result in a macroexpansion buffer. If invoked with a prefix argument, pprint the result.
  • 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: Select the repl 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
  • M-.: Jump to the definition of a var. If invoked with a prefix argument, or no symbol is found at point, prompt for a var.
  • M-,: Return to your pre-jump location.
  • M-TAB: Complete the symbol at point. (For auto-complete integration, see ac-nrepl)

REPL buffer commands:

  • 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. Also bound to M-RET.
  • 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: 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.

Requirements:

Contributing

License

Copyright © 2012 Tim King, Phil Hagelberg and contributors.

Distributed under the GNU General Public License, version 3