Emacs is a freely available, open source text editor which runs in both terminal windows (Figure 18.1, “An Emacs window showing the SLIME inspector and debugger at work.”) and GUIs on a very wide variety of platforms. There are several ports, the most popular being GNU Emacs. You’ll find a good general-purpose introduction on Wikipedia, much more detail in the O’Reilly book Learning GNU Emacs by Debra Cameron, Bill Rosenblatt and Eric Raymond, and an extensive project website at

http://www.gnu.org/software/emacs/

Much of Emacs is written in Lisp. Emacs can be extended by writing more Lisp. Every character you type (whether the plain letter “q” or some fancy control sequence) invokes a Lisp function; in the finest traditions of Lisp such functions can be defined and redefined on the fly, i.e. without restarting Emacs. When it starts up, Emacs loads Lisp forms from the .emacs file (if you have one) in your home directory. Most long-standing Emacs users will have accumulated a number of personalizations in their .emacs over the years, whether forms to load various libraries (such as SLIME), or tweaks to the Emacs source, or functionality extensions. I’m using Emacs to write this book; here as an example of Lisp that's not Common Lisp is the part of my .emacs which I added to support this activity.

;; Control whether quotes are curly (“”) or straight ("")

(global-set-key [f9] 'toggle-sgml-quotes)

(define-key sgml-mode-map "'" 'sgml-insert-single-quote)
(define-key sgml-mode-map "\"" 'sgml-insert-double-quote)

(defvar sgml-quotes-p nil)

(defun toggle-sgml-quotes ()
  (interactive)
  (setf sgml-quotes-p (not sgml-quotes-p))
  (message (format "Fancy quotes %s" (if sgml-quotes-p "on" "off"))))

(defun sgml-insert-single-quote ()
  (interactive)
  (insert (if sgml-quotes-p "’" "'")))

(defun sgml-insert-double-quote (p)
  (interactive "P")
  (insert (if sgml-quotes-p
              (if p "”" "“")         ; C-u " for close quote
            "\"")))

The Lisp in Emacs, Emacs Lisp provides built-in support for programming the Emacs text editor with functions such as global-set-key in the example above. But the language is not Common Lisp. It’s a lot smaller; there are some important differences (for example, all variables have dynamic scope) and a host of lesser ones (e.g. format is different, as you’ll have noticed in toggle-sgml-quotes). You can read more about Emacs Lisp in the O’Reilly book mentioned above or by following links from the Emacs project website. You can extend Emacs Lisp to something closer to Common Lisp by evaluating the form

(require 'cl)

Emacs is much more than an editor. Of particular interest here: you can run shells in Emacs windows; you might then run an interactive Lisp session in such a shell. Emacs supports this with Inferior Lisp mode (the word “inferior” here is not a value judgement but means that Lisp is running as a subprogram under the auspices of Emacs). And then, for example, if you’re editing Lisp code the key binding M-C-x sends the definition under the cursor to your inferior Lisp for evaluation. SLIME is a rich extension of the Inferior Lisp mode.

Emacs comes bundled with Linux, FreeBSD, and Mac OS X.

This should be very straightforward. The project home page for SLIME:

http://common-lisp.net/project/slime/

includes links for a thorough manual, an hour-long video tutorial, the slime-devel mailing list which should be your first port of call if you need technical help, and for downloads:

http://common-lisp.net/project/slime/snapshots/slime-current.tgz

Download and unpack the distribution, for example using curl and tar as described under “Download” in Chapter 17, Image Processing. Configure SLIME by adding forms to your .emacs, along the following lines:

(setq inferior-lisp-program "/home/ndl/lisps/ccl/scripts/ccl")
(add-to-list 'load-path "/home/ndl/chapter-18/slime-2009-08-26/")
(require 'slime-autoloads)
(slime-setup '(slime-fancy))

I really did hope to write this book without mentioning setq. Think of it as a prehistoric setf which only works on symbol values. If you (require 'cl) then Emacs will understand setf.

Finally, evaluate the above forms (e.g. M-x eval-region) and start SLIME itself:

M-x slime

When SLIME starts, it fires up the inferior Lisp and loads into it a server called Swank with which it then communicates using a socket protocol. Swank comes with a backend file for every supported implementation.

SLIME creates three initial buffers, two of which are not much use other than for troubleshooting. *inferior-lisp* is your Lisp’s top level; depending on platform it might contain a working REPL but if it does it will lack the power provided by the listener in the main REPL buffer (named *slime-repl ccl* on CCL, etc.) which you’ll find topmost. *slime-events* contains a full log of communications between SLIME and the inferior Lisp.

Some SLIME features don’t work with all Lisps. This will depend on what the underlying implementation supports. Look for “Warning: These Swank interfaces are unimplemented” in the *inferior-lisp* buffer. (We’ll restrict ourselves here to features with universal support.)

In both source files and the listener, M-TAB completes the symbol under point. M-C-i is an equivalent key binding which you may find more natural to work with (and on Windows and Mac OS it won't be intercepted by the window manager!). In the listener TAB on its own has a dual action: it attempts to indent but if that doesn’t change anything then it performs symbol completion instead. So TAB TAB is generally a quick and easy way to fix listener indentation and complete the current symbol.

SLIME’s completion can expand each component of a hyphenated symbol: m-v-b completes to multiple-value-bind and h--t to hash-table-test. It also provides context-sensitive completion for keywords: (make-array 3 :e<TAB> completes the keyword to :element-type (because no other keywords starting with :e are valid here).

The space key inserts a space character but has a secondary action in both source files and the listener: it prints to the echo area the argument list of the operator which you’re working on, highlighting the argument which comes next (Figure 18.2, “Interacting with the listener. The echo area shows the argument list for the form we’re entering and the *Completions* buffer lists all external symbols in the ASDF package starting with the character *.”). If you want to do this without inserting spaces (for example, in a read-only buffer) then use M-x slime-arglist.

You can look up Hyperspec documentation for the symbol under point with C-c C-d h and (an occasional lifesaver) for the format character under point with C-c C-d ~. Both of these will open a web browser using the function named by the Emacs variable browse-url-browser-function. If you have a local copy of the Hyperspec then reset common-lisp-hyperspec-root, along the lines of "file:/usr/local/doc/HyperSpec/".

The slime-selector command is a shortcut for switching buffers. It doesn’t have a default key binding but you can fix that, by adding this or similar to your .emacs:

(global-set-key (kbd "C-c s") 'slime-selector)

It offers you a choice of single letter “commands” for specifying which buffer you’re after, among which are:

The upshot of this is that C-s s r will take you back to the REPL.

M-. locates source code: it takes you to the definition of the symbol under point. The information for this (which definition was loaded from where) comes from your inferior Lisp. Unless you’ve configured Lisp not to store definition locations (see Chapter 28, World Building for more on this) M-. should always work on your own code. If you’re using one of the open source Lisps, it might also give you easy access to underlying implementation details.

Note while you’re floating around the source that SLIME understands reader conditionals: #+not-this-one will “grey out” a code block in the same way that semicolons do to a single line.

If you’ve used M-. then M-, will take you back to where you were beforehand. M-. pushes locations onto a stack and M-, pops it.

Once you’ve found the function you’re looking for, maybe you’d like to trace it? Use C-c C-t to toggle whether the symbol at point is traced.

The workhorse for compiling and executing the top-level form at point is C-c C-c. You can control optimizations by supplying a numeric prefix argument: positive for maximal debuggability, negative to compile for speed.

To compile and load the current source file, use C-c C-k.

If the compiler hits badly broken syntax, such as (if), then an error will be signaled and you'll be thrown into the debugger. See the section called “SLDB: The Debugger” below for how to get out that.

If the compiler issues any notes or warnings then the offending forms will be annotated (by underlining them) and the warnings listed in a *SLIME Compilation* buffer (Figure 18.4, “Compiler warnings provoked by two deliberate mistakes. The source for all warnings is underlined and the “current” one highlighted, a description of the warning itself is in the echo area. Use M-n (next) and M-p (previous) to cycle through the warnings.”). If you’re running Emacs in a GUI then place the mouse over an annotation to see its message as a popup. Otherwise, cycle through the messages using M-n to go to the next note and M-p to back up. When you’re done, clear the annotations from the buffer with C-c M-c.

SLIME also provides commands for evaluating without explicit invocation of the compiler. In particular, M-C-x evaluates the current top-level form. Note that if the form is a defvar then the variable concerned will be reset even if it already had a value (as if the form were a defparameter).

Any errors signaled by the inferior Lisp are debugged in a popup SLDB buffer (Figure 18.5, “Entering the debugger. The condition is reported first, followed by the restarts. A backtrace follows further down.”). SLDB supplies a number of commands for navigating through stack frames and invoking restarts. You don’t have to remember what all of these are because RET will (to quote the SLIME manual) “do the most obvious useful thing”.

You need to know what’s going on inside your data structures; poking around in the guts of objects which you’ve grabbed from the listener or debugger should become second nature. This is where the inspector, one of the most powerful tools available to Lisp programmers, comes in. This is a tool for displaying a “snapshot“ of some Lisp object, exposing its components and allowing you to reset them or inspect them recursively.

We’ve already met the SLDB shortcuts for invoking the inspector. If you’re in another SLIME buffer use C-c I. Like i in the debugger this prompts for a value to inspect, defaulting to the value at point.

The inspector’s display varies according to the class of the object you’re inspecting. The convention is to show a human-readable description at the top followed by a list of internal values (methods for a generic function, slots for a general CLOS object, and so on).

Once you’re in the inspector, as for the debugger, RET acts as a context-sensitive operator. If point is on a value then RET will inspect that instead; if point is on an action—these are displayed in bright red and within square brackets—then either RET or a mouse click will invoke it. Actions are themselves context-sensitive and include removing function definitions from symbols, setting or unbinding slot values, clearing hash tables.

SLDB maintains a stack of inspected values: each time you press RET to inspect something, a new inspected value gets added to the stack (and shown to you). You can navigate back to previous inspected values with l. Use either n or SPC to go the other way and retrace your steps further in.

Two other useful inspector key bindings are:

We saw earlier a basic configuration technique for SLIME: you register the location of an inferior Lisp, tell Emacs where to find SLIME, and then call:

(require 'slime-autoloads)
(slime-setup '(slime-fancy))

The require form above means that SLIME will be loaded “on demand” when you need it. If you’d rather always load SLIME when Emacs is started, replace that form with (require 'slime). If you’d like to guarantee that SLIME is running whenever you open a Lisp file, add the following to your .emacs (this will work with either require form):

(add-hook 'slime-mode-hook
          (lambda ()
            (unless (slime-connected-p)
              (save-excursion (slime)))))

The argument to slime-setup is an optional list of “contributed modules” to be loaded alongside SLIME itself. To load SLIME on its own you’d replace the call with (slime-setup). Not all of the contributed modules are documented in the manual; the best way to see what’s on offer is to look through SLIME’s contrib/ subdirectory. Specifying slime-fancy gives you a usable set of about half of the available modules (see contrib/slime-fancy.el). As noted before, this chapter is based on the assumption that slime-fancy has been loaded.

You’re not confined to always using the same inferior Lisp. If you invoke M-x slime with a prefix argument you’ll be prompted for the Lisp to run. If the prefix is negative (M-- M-x slime) you’ll be offered a choice based on the value of slime-lisp-implementations; you’ll find this variable described in the SLIME manual in the Setup Tuning section, under Multiple Lisps.

In addition to the configurations above, both SLIME and Swank can be customized. For SLIME, use the Emacs facility M-x customize-group slime. The available options are documented within the customization system (sometimes rather tersely). You might want to start by considering slime-truncate-lines (in the Slime Ui group). This is on by default and means that line wrapping is disabled in popup buffers (such as backtraces).

Swank is customized by setting variable values in your ~/.swank file. The available options are documented in the SLIME manual. Take note of swank:*communication-style* which governs the interaction between Emacs and Swank. Each backend defines an appropriate value for this variable; for preference this should be :spawn (meaning: execute each request in a separate thread).

You can invoke macroexpansion of the form beginning or ending at point with any of:

The macroexpansion appears in a popup buffer (so you can close it with q). Further macroexpansions from the popup buffer modify its contents rather than opening further buffers.

SLIME manages indentation of macro bodies (for example: in a macroexpansion buffer, or in the listener) by treating &body arguments specially. Usually this works out fine. But if you happen to have two macros named with the same symbol-name (in different packages) then SLIME will arbitrarily choose the argument list of one to indent the other. List such collisions by calling (swank:print-indentation-lossage) and fix them on the Emacs side by setting the losing symbol’s common-lisp-indent-function property.

SLIME caches symbols’ indentation properties. It will stay up-to-date on macro definitions in the current package. When a new package is created (typically this means you’ve been loading code) SLIME scans every symbol in the system. These strategies are usually good enough and in the rare cases when they’re not you can force an update with M-x slime-update-indentation.

The separation of SLIME into an Emacs interface and the Swank backend makes it relatively easy to run the Emacs side and Lisp session on different machines. This practice might come in handy if you ever need to debug a remote server. You’ll need ssh access to the server’s host and you might want to perform the first of the following steps before the server runs aground.

If you want to serve Swank on a port other than 4005 then specify a value for :port in the call to swank:create-server and change the second number in the ssh setup accordingly. For example: (swank:create-server :port 84005 :dont-close t) and ssh -L4005:127.0.0.1:84005 username@remote.example.com. (You can also switch the local port number by changing the first number in the ssh setup and overriding the value offered by the slime-connect command.)

If you want to share source files between client and server, you can do this using TRAMP (remote file editing module for GNU Emacs). Load the slime-tramp module from SLIME’s "contrib/" directory into your local Emacs session and check out the section “Setting up pathname translations” in the SLIME manual.

The inspector display is controlled by the generic function swank-backend:emacs-inspect. Several methods will be defined on this already. You should feel free to raid them as templates for adding more if you need to specialize the display.

Each method takes an object as its single argument and should return a list specifying how to render the object for inspection. Every element of the list must be one of the following forms:

Here’s a very simple example:

(defclass animal ()
  ((legs :accessor animal-leg-count :initform 0)))

(defmethod swank-backend:emacs-inspect ((self animal))
  (let ((count (animal-leg-count self)))
    `("Hello. "
      (:value ,count ,(format nil "This animal has ~r leg~:p." count))
      (:newline) (:newline)
      (:action "Grow another one"
               ,(lambda () (incf (animal-leg-count self)))))))

A new instance of animal will look like this in the inspector:

#<ANIMAL 200CE94F>
--------------------
Hello. This animal has zero legs.

Grow another one

Select the first line of text to inspect the number zero. Click on the action to increment the animal’s legs slot and update the display.