clojure-mode and slime

As a long time user of SLIME I was a bit disappointed to see clojure-mode 2.0 drop support for it in favor of nrepl. I looked into nrepl but found it to be not as feature complete as SLIME, at present. Also, I still work on some sizeable Common Lisp code, which relies entirely on SLIME, and I want to be able leverage any tooling work I do across all my projects – so SLIME wins.

As it turns out, it wasn't at all difficult to resurrect the SLIME integration code from clojure-mode 1.x and load it alongside the newer clojure-mode.

I've committed the clojure-mode-slime.el Emacs Lisp code into the following repo, along with some other Clojure/Emacs hacks:

http://github.com/kriyative/clojure-emacs-hacks

I hope this is useful to other SLIME die-hards in the Clojure community as well. Feedback and bug reports are most welcome.

clojure, emacs, and docs redux

A while back I'd written about looking up Javadocs from Clojure mode buffers. I got some good feedback on that post, so I thought I'd try and expand on that and see if I could integrate other Clojure documentation sources into a similar workflow.

view javadocs in emacs/w3m (click to view full size)

Looking up Clojure doc strings within Emacs is really easy. In any Clojure code buffer, you can place your cursor at a symbol and use C-c C-d d or M-x slime-describe-symbol to bring up the function or var doc string.

Previously, I'd made a slime-javadoc command that could be configured to search external Javadoc sources only. However, that mechanism could be applied more generally to more sources.

The new command M-x clojuredocs, can show either Javadocs for Java classes, or goes to the excellent clojuredocs.org site for documentation specific to clojure.core and a few other namespaces (such as ring), or eventually fallsback to a simple Google search.

So, after connecting to a Clojure instance (via clojure-jack-in or slime-connect), I can invoke M-x clojuredocs on any symbol and get back some relevant documentation or at the least som helpful pointers from Google.

I've committed an initial version of the Emacs Lisp code into the following github repo:

http://github.com/kriyative/clojure-emacs-hacks

Feedback and bug reports are most welcome.

New Site

This is my shiny new site hosted on github.com. I used to previously blog at funcall.posterous.com and cynojure.posterous.com, but I think github may be a more natural fit for my edit and publish workflow. After all, most of my professional and hobbyist programming work lives here, so why not my blog.

Incidentally, I'm using org-mode in Emacs to author the posts and a modified version of the static blog generation tool to generate the HTML and RSS.

Emacs for Clojure - Part 2

This is the second in a two part post about a Clojure programmer workflow entirely within Emacs.

Editing Clojure

Some useful navigation key bindings in Clojure-mode, actually any Lisp code editing mode in Emacs, are as follows:

KeybindingCommand
C-M-fforward-sexp
C-M-bbackward-sexp
C-M-abeginning-of-defun
C-M-eend-of-defun
C-M-xslime-compile-defun
C-x C-eslime-eval-last-expression

Some of these key bindings get redefined when a buffer is in slime-mode to SLIME enhanced equivalents, but mostly they behave the same.

And, don't forget the exponential effect of the C-u prefix key.

Some other key bindings that are also useful are:

KeybindingCommandDoc
C-M-qindent-sexpA lot of times when copying and pasting or otherwise modifying large blocks of s-expressions, the indentation of the code can get out of whack. indent-sexp can help restore the balance.
C-M-hmark-defun
C-M-kkill-sexp

Also worth knowing, the magic of dynamic abbrevs bound to the M-/ key binding. Dynamic abbrevs are a quick way to complete a long function or var name from a minimal prefix. It's very brute force (i.e, just searches for a match in all the open buffers), but since it's very fast, it comes in handy when you're working with partially evaluated Clojure code.

Clojure REPL

Everything begins with a Clojure instance which has SWANK loaded. Again, there are lots of ways of starting one of these, and the most common use case is with a Leiningen project setup. Setting up Leiningen is beyond the scope of this post, but the docs on Leiningen's github page are quite helpful in getting you started.

Once Leiningen is setup and you have a project.clj file for your project, you can invoke clojure-jack-in.

Once SLIME is connected, it's helpful to know the following commands:

KeybindingCommandDoc
slime-replThis is a quick way to jump to the *slime-repl clojure* buffer.
slime-resetWhen your SLIME connection goes out of whack.
C-M-islime-complete-symbol
C-x eslime-eval-last-expressionMakes every Clojure buffer into a REPL. Plus, it is very handy when iterating on tests.
C-c C-c, C-M-xslime-compile-defunThis is convenient for compiling a defn or other top-level form, without having to put the cursor at the end of the expression.
slime-list-connectionsIf you find yourself having to connect to multiple SWANK servers this command is helpful in switching between them.
slime-list-threadsShow the list of scheduled JVM threads, and can provides an interactive way to kill running threads. Use with caution.

Emacs for Clojure - Part 1

This is a brief overview of the way I work in Clojure using Emacs - almost exclusively. Obviously, Emacs is not the only way to interact with Clojure, but it can be a pretty seamless and efficient environment for Clojure, once you become familiar with the powerful extensibility and "mouse-free" efficiency of Emacs.

Also, since Emacs uses Lisp as its extension language, there's a lot of value for a Clojure/Lisp developer in learning and mastering the Emacs' ecosystem. I hope this series of posts will be helpful in that endeavour.

There are lots of "getting started with Emacs" docs available online and on the web. The easiest one is the built-in Tutorial, which you can also bring up within Emacs with C-h t or M-x help-with-tutorial. Other online references:

  1. A Guided Tour of Emacs
  2. A Tutorial Introduction to GNU Emacs

For the most part, I'm going to assume you're using Emacs default key bindings, but the following customizations don't really depend on that.

Process

My typical work-flow involves the following steps (but not necessarily in the same order always):

(loop []
  ;; Edit code/tests
  ;; Interactive development with REPL and tests
  ;; Look up documentation
  ;; Search and Navigate a code tree
  ;; Run batch tests
  ;; Merge commits and resolve conflicts in Git
  (recur))

I'll try to cover each of these steps in detail over the course of the next few posts.

Clojure Mode Setup

Like snowflakes and Sting albums, there are myriad ways of setting up the Clojure environment in Emacs, but essentially all of them should be doing something similar to the following:

(defun clojure-mode-hook ()
  (setq indent-tabs-mode nil
        clojure-mode-use-backtracking-indent t)
  (setup-clojure-indentation-rules))
(require 'clojure-mode)
(require 'clojure-test-mode)
(require 'swank-clojure)
(add-hook 'clojure-mode-hook 'clojure-mode-hook)
(add-hook 'clojure-mode-hook 'clojure-test-mode)

If you are using Emacs 24 and have never setup Clojure-mode or SLIME before, check out the emacs-starter-kit.

Basic Editing

It's good to get familiar with the basic cursor movement keys such as:

KeybindingCommand
C-nnext-line
C-pprevious-line
C-fforward-char
C-bbackward-char
C-amove-beginning-of-line
C-emove-end-of-line

There's been a lot of cursing and teeth gnashing about Emacs' default key bindings, but here are some of the benefits that I've come to appreciate over time:

  1. Clustering – you can insert and move around with minimal physical movement from the home row of the keyboard.
  2. Easy to remember
  3. Work in bash and even on tty devices (never say never) - this is particularly useful if you're planning to do some remote pairing over tmux or screen

And, there is always C-h b describe-bindings which will list the key bindings in any given buffer.

Other useful basic key bindings:

KeybindingCommandDoc
C-lrecenterredraw buffer with the current line at the vertical center of the window; one useful variation is to C-u 0 C-l which will redraw the buffer with the current line at the top of the window
C-SPCset-mark-commandset the beginning of a copy/cut region, and move the cursor to the end of the region
C-wkill-regioncut the contents of the selected region
M-wkill-ring-savecopy (not cut) the contents of the selected region
C-yyankpaste the most recently copied/cut region at cursor point
M-yyank-popwhen used after a yank, Emacs will replace the pasted region with older copied text cycling through the cut/copy history
C-x r kkill-rectanglemark a region as you would normally, but cut a rectangular sub-region. Useful when working with columns of data
C-x r yyank-rectanglepaste the most recently killed rectangular region

Keyboard Macros

We've all been in situations where we've had to fix up some literal data structure or otherwise munge code by repeating a set of editing keystrokes, either deleting, inserting or otherwise splicing text. Keyboard macros can quickly help automate some of this work.

The basic principle is that you begin recording a macro C-x ( kmacro-start-macro, perform the keyboard actions, and then end recording with C-x ) kmacro-end-macro. You can then replay the macro using C-x e kmacro-end-and-call-macro. Also, check out C-x C-k n kmacro-name-last-macro for oft repeated macros.

Next post: REPL, SLIME and interactive programming.