The Common Lisp Cookbook – Using Emacs as an IDE

Table of Contents

The Common Lisp Cookbook – Using Emacs as an IDE

This page is meant to provide an introduction to using Emacs as a Lisp IDE. The key bindings used in the example code snippets assume an Emacs configuration similar to that provided by the .emacs file that is included as part of the Setting up an IDE with Emacs on Windows or Mac OS X page.

Note: Portacle is a portable and multi-platform CL development environment, a straightforward way to get going.

Why Use Emacs?

Emacs Lisp vs Common Lisp

SLIME: Superior Lisp Interaction Mode for Emacs

SLIME is the goto major mode for CL programming.

Check out this video tutorial ! (and the author’s channel, full of great stuff)

SLIME also has some nice extensions like Helm-SLIME which features, among others

REPL interactions

From the SLIME REPL, press , to prompt for commands. There is completion over the available systems and packages. Examples:

and many more.

With the slime-quicklisp contrib, you can also ,ql to list all systems available for installation.

SLY: Sylvester the Cat’s Common Lisp IDE

SLY is a SLIME fork that contains the following improvements:

Working with Lisp Code

In this short tutorial we’ll see how to:

Packages for structured editing

In addition to the built-in Emacs commands, you have several packages at your disposal that will help to keep the parens and/or the indentation balanced. The list below is somewhat sorted by age of the extension, according to the history of Lisp editing:

We personally advice to try Parinfer and the famous Paredit, then to go up the list. See explanations and even more on Wikemacs.

Editing

Forward/Backward/Up/Down movement and selection by s-expressions

;; Put the cursor on the open parens of "(defvar.." and press "C-M-f"
;; and "C-M-b" a few times to see how you move in units of sexps. Put
;; the cursor on the second additon in the "(progn" statement and
;; press "C-M-t" to swap the first addition sexp and the second
;; one. Put the cursor on the open parens of "(+ x" in defun c and
;; press "C-M-@" to highlight the entire sexp. Then press "C-M-u" to
;; expand the selection "upwards" to the enclosing "(let". Pressing
;; "C-M-d" moves to the next enclosed sexp or (if you are at the
;; beginning of a line) to the enclosed sexp on the line: 

(defvar a "a variable")

(defun b ()
  "a function"
  (+ 2 2))

(defun c ()
  "another function"
  (let ((x 42))
    (+ x
       (+ 2 2)
       (+ 3 3)
       (+ 4 4))))

(progn
  (+ 1 1)
  (+ 2 2)
  (+ 3 3))

Deleting s-expressions

With C-M-k and C-M-backspace (which may restart the system on gnu/linux):

;; Put the cursor on the open parens of "(progn .." and press "C-M-k"
;; to delete it. Then press "C-M-backspace" to delete the sexp before
;; the cursor (caution, on gnu/linux this keybinding may mean to
;; restart the system):

(defun d ()
  (if t
      (+ 3 3)
      (progn
        (+ 1 1)
        (if t
            (+ 2 2)
            (+ 3 3)))
      (+ 4 4)))

Indenting s-expressions

With C-M-q:

;; Put the cursor on the open parens of "(defun ..." and press "C-M-q"
;; to indent the code:

(defun e ()
"A badly indented function."
(let ((x 20))
(loop for i from 0 to x 
do (loop for j from 0 below 10 
do (print j)) 
(if (< i 10)
(let ((z nil) )
(setq z (format t "x=~d" i))
(print z))))))

;; This is the result:

(defun e ()
  "A badly indented function."
  (let ((x 20))
    (loop for i from 0 to x 
       do (loop for j from 0 below 10 
             do (print j)) 
         (if (< i 10)
             (let ((z nil) )
               (setq z (format t "x=~d" i))
               (print z))))))

Support for parenthesis

M-( insets a pair, M-x check-parens to spot malformed sexps, C-u <n> M-( to enclose sexps with parens:

;; Placing the cursor on a "(" or after a ")" highlights the matching
;; parens:

(progn (+ 3 3) (- 2 2))

;; A mismatched parens is highlighted in a different color (put cursor
;; after last parens and enter a ")" to see this:

(- 2 2)

;; You can also type "M-x check-parens" to locate mismatched parens in
;; a buffer

;; Press "M-(" and you will get:

() 

;; with the cursor placed on the closing parens, ready to enter the
;; function name. 

;; Put the cursor on the open parens of the "(+ 2 2)" sexp below and
;; press "C-u 2 M-(" to enclose the next 2 sexps with parens - then
;; type "+ 1" to add "1" to the result of the following 2 sexps:

(progn (+ 2 2) (+ 3 3))

;; To delete the enclosing "progn" below, put the cursor on the open
;; parens of the "(+ 1 1)" and press the following sequence of keys:
;; "C-M-k C-M-k C-M-k C-M-u C-M-k C-y M-y C-M-a C-M-q":

(defun a ()
  (progn 
    (+ 1 1)
    (+ 2 2)
    (+ 3 3)))

Automatic code indentation

;; Indentation is automatic for Lisp forms. Example: Put the cursor
;; after the first addition form and press Enter:

(progn
  (+ 3 3)
  (- 2 2))

;; Pressing TAB will indent incorrectly indented code. Example: Put
;; the cursor at the beginning of the "(+ 3 3)" form and press TAB:

(progn
(+ 3 3))

;; CL indentation rules are different from Emacs Lisp indentation
;; rules. Make certain you have the following code in a lisp mode hook
;; in your .emacs file:

(set (make-local-variable lisp-indent-function)
     'common-lisp-indent-function)

Code completion

Use the built-in C-c TAB to complete symbols in SLIME. You can get tooltips with company-mode.

;; The Emacs hippie-expand command will expand lisp symbols
;; (however, it only works off of lisp symbol information that is
;; either available in the buffers or a standard CL symbol) and
;; directories. For example, type in the following and press "C-c /"
;; to get a directory completion:

(setq x "c:/pro

Hiding/showing code

With C-x n n (narrow) and C-x n w to widen back.

See also code folding.

;; Highlight the middle "(if ..." block and press "C-x n n" to hide
;; everything but that block ("C-x n w" restores the other code):

(if a 
    (+ 1 1))
(if b
    (+ 2 2))
(if c
    (+ 3 3))

;; Put the cursor on "(defun b ..." and press "C-x n d" to narrow to
;; just defun b (("C-x n w" restores the other code):

(defun a ()
  (+ 1 1))

(defun b ()
  (+ 2 2))

(defun c ()
  (+ 3 3))

Comments

Insert a comment, comment a region with M-;, adjust text with M-q.

;; Put the cursor on the following sexp and press "M-;" to get a
;; code line comment (right-hand comment):

(setq x 1)

;; Highlight the 2nd & 3rd lines and press "M-;" to comment out those
;; lines (highlighting them a 2nd time and pressing "M-;" removes the
;; comment):

(+ 1 1)
(+ 2 2)
(+ 3 3)

;; Using Paul Foley's comment functions allows you to selectively
;; comment out embedded sexps. Example: Put the cursor on the "(+ 4
;; 4)" sexp and press "C-c ;" to comment out that sexp. Pressing "C-c
;; ;" comments out the enclosing sexp (and on upwards). Pressing "C-c
;; :" removes the comment:

(+ 1 (+ 2 (+ 3 (+ 4 4))))

;; Emacs knows how to wrap comment text intelligently. For example, this comment line spans
;; muliple lines but is not aligned consitently
;; with the rest of the comments/code in the file (everything else
;; ends at
;; column 68. Pressing "M-q" adjusts the comments appropriately.

Evaluating and Compiling Lisp in SLIME

Compile the entire buffer by pressing C-c C-k.

Compile a region by selecting the first 2 forms in test-all and running M-x slime-compile-region.

Compile a defun by putting the cursor inside the “test-format” defun and pressing C-c C-e.

Compile the sexp before the point by putting the cursor after the closing paren of (test-format) and pressing C-c C-e.

To evaluate rather than compile:

Searching Lisp Code

Standard Emacs text search (isearch forward/backward, regexp searches, search/replace)

C-s does an incremental search forward (e.g. - as each key is the search string is entered, the source file is searched for the first match. This can make finding specific text much quicker as you only need to type in the unique characters. Repeat searches (using the same search characters) can be done by repeatedly pressing C-s

C-r does an incremental search backward

C-s RET and C-r RET both do conventional string searches (forward and backward respectively)

C-M-s and C-M-r both do regular expression searches (forward and backward respectively)

M-% does a search/replace while C-M-% does a regular expression search/replace

Finding occurrences (occur, grep)

With M-x grep, rgrep, occur,…

;; Use the Emacs "occur" function to find all occurances of a string
;; (or regexp) in a buffer. Example: Enter "M-x occur" and enter the
;; string "defun" to get a list of all the occurances of the
;; characters "defun" in the current buffer.

(defvar aa "a" "a variable")

(defun b ()
  "a function"
  (+ 2 2))

(defun c ()
  "another function"
  (+ 3 3))

(defmacro d (x)
  "a macro"
  `(list ,x))

;; Use the Emacs "grep" function to find all occurances of a string
;; (or regexp) in a multiple files. Example: Enter "M-x grep" and
;; enter the string "defun *.lisp" to get a list of all the function
;; definitions in lisp files in the current directory.

See also interactive versions with helm-swoop, helm-occur, ag.el.

Lisp symbols in current source (imenu)

;; Open a lisp source file and press the middle mouse button for a
;; pop-up window listing all variables and functions in the lisp
;; source file.

See also helm-imenu and imenu-anywhere.

Go to definition

Put the cursor on any symbol and press M-. to go to its definition. Press M-, to come back.

Crossreferencing: find who’s calling, referencing, setting a symbol

Slime has a nice cross referencing facility, for example, you can see what calls a particular function or expands a macro. It presents a list of places which reference a particular entity, from there you can recompile the thing which references by pressing C-c C-c on that line. C-c C-k will recompile all the references. This is useful when modifying macros, inline functions, or constants.

The following bindings are also shown in Slime’s menu:

And when the slime-asdf contrib is enabled, C-c C-w d slime-who-depends-on lists dependent ASDF systems

And a general binding: M-? or M-_ *slime-edit-uses** combines all of the above, it lists every kind of references.

(thanks to Slime tips)

Lisp symbols in multiple source files (etags)

;; Enter "M-x shell" to bring up a shell window in the current
;; directory. Then run "etags *.lisp" to create a TAG file containing
;; all symbols in lisp files in the current directory. Then run "etags
;; -a subdir/*.lisp" to add to the TAG file symbols from all lisp
;; files in another directory. Locate the definition of the "aa"
;; variable is the s13.lisp file by putting the cursor on the "aa" in
;; the following form and pressing "M-.".

(setq x aa)

Lisp symbols using ECB, the Emacs Code Browser ( s17.lisp )

;; Press "M-x ecb-activate" to start up ECB. Load a lisp file by
;; pressing the middle mouse button (or the Enter key) on any file
;; name in the ECB mini-window. Pressing the middle mouse button (or
;; the Enter key) on any definition in the ECB symbol mini-window
;; takes you to that definition. Press "C-F7" to toggle between full
;; screen and ECB views.

Lisp Documentation in Emacs - Learning About Lisp Symbols

Argument lists

When you put the cursor on a function, SLIME will show its signature in the minibuffer.

Documentation lookup

Other bindings which may be useful:

Documentation

;; Enter and evaluate the following definitions, then put the cursor
;; on "(xx)" and press "C-c C-d d" to get the function documentation.

(defun xx ()
  "A do-nothing function"
  nil)

(setf (documentation 'xx 'function) "A function that does nil.")

(xx)

Inspect

;; Enter and evaluate the following definitions, then put the cursor
;; on "(xx)" and press "C-c I" or "C-c C-v C-i" (SLIME) to execute "inspect" on
;; the "xx" function. Entering "h" gives a list of help commands and
;; "q" exits the inspector.

(defun xx ()
  "A do-nothing function"
  nil)

(setf (documentation 'xx 'function) "A function that does nil.")

(xx)

Macroexpand

;; Enter the following function definition, then put the cursor on the
;; open parens of "(defun ..." and call "M-x slime-macro-expand-1" to
;; get a macroexpand-1. Then press "C-c M-m" to get a recursive
;; macroexpansion. See also the menu.

(defun test (n)
  (loop for i from 0 below n
     do (print i)))

Lisp Documentation in Emacs - Lisp Documentation

;; Put the cursor on the "(format" below and press "C-c C-d d" or "F1"
;; with the example emacs configuration to get the Hyperspec page for
;; "format". Put the cursor on the "d" in the format string and press
;; "C-u F1" to get the Hyperspec page describing the "Tilde D:
;; Decimal" format character.

(format t "One = ~d" 1)

;; Note: Depending on the documentation packages that have been
;; loaded, and the browser that you wish to use, the following keys
;; may be used:
;;            Default    W3
;; Package    Browser  Browser  Format-Dft  Format-W3  Info
;; =========  =======  =======  ==========  =========  ====
;; Hyperspec    F1      S-F1    C-u F1      C-u S-F1
;; CLtL2       M-F1    M-S-F1
;; ACL docs    C-F1    C-S-F1
;; Info docs                                           C-M-F1

Consult the CLHS offline

(ql:quickload "clhs")

Then add this to your Emacs configuration:

(load "~/.quicklisp/clhs-use-local.el" 'noerror)

Miscellaneous

Synchronizing packages

C-c ~ (slime-sync-package-and-default-directory): When run in a buffer with a lisp file it will change the current package of the REPL to the package of that file and also set the current directory of the REPL to the parent directory of the file.

Calling code

C-c C-y (slime-call-defun): When the point is inside a defun and C-c C-y is pressed,

(I’ll use [] as an indication where the cursor is)

(defun foo ()
 nil[])

then (foo []) will be inserted into the REPL, so that you can write additional arguments and run it.

If foo was in a different package than the package of the REPL, (package:foo ) or (package::foo ) will be inserted.

This feature is very useful for testing a function you just wrote.

That works not only for defun, but also for defgeneric, defmethod, defmacro, and define-compiler-macro in the same fashion as for defun.

For defvar, defparameter, defconstant: [] *foo* will be inserted (the cursor is positioned before the symbol so that you can easily wrap it into a function call).

For defclass: (make-instance ‘class-name ).

Inserting calls to frames in the debugger

C-y in SLDB on a frame will insert a call to that frame into the REPL, e.g.,

(/ 0) =>
…
1: (CCL::INTEGER-/-INTEGER 1 0)
…

C-y will insert (CCL::INTEGER-/-INTEGER 1 0).

(thanks to Slime tips)

Send to the REPL

;; With the cursor on the "let", press "C-x C-e" (Slime) to
;; evaluate a lisp form by sending it to the REPL.

(let ((n 20))
  (loop for i from 0 below n
     do (print i)))

See also eval-in-repl to send any form to the repl.

Exporting symbols

C-c x (slime-export-symbol-at-point) from the slime-package-fu contrib: takes the symbol at point and modifies the :export clause of the corresponding defpackage form. It also exports the symbol. When called with a negative argument (C-u C-c x) it will remove the symbol from :export and unexport it.

M-x slime-export-class does the same but with symbols defined by a structure or a class, like accessors, constructors, and so on. It works on structures only on SBCL and Clozure CL so far. Classes should work everywhere with MOP.

Customization

There are different styles of how symbols are presented in defpackage, the default is to use uninterned symbols (#:foo). This can be changed:

to use keywords:

(setq slime-export-symbol-representation-function
      (lambda (n) (format ":%s" n)))

or strings:

(setq slime-export-symbol-representation-function
 (lambda (n) (format "\"%s\"" (upcase n))))

Project Management

ASDF is the de-facto build facility. It is shipped in most Common Lisp implementations.

Comparing versions of code (ediff)

Start the ediff utility by entering M-x ediff. Enter two file names, press the space bar to step through the changes, and q to exit.

Of course, see also magit for a wonderful git integration into Emacs.

Questions/Answers

utf-8 encoding

You might want to set this to your init file:

(set-language-environment "UTF-8")
(setenv "LC_CTYPE" "en_US.UTF-8")

and for Sly:

(setq sly-lisp-implementations
          '((sbcl ("/usr/local/bin/sbcl") :coding-system utf-8-unix)
            ))

This will avoid getting ascii stream decoding errors when you have non-ascii characters in files you evaluate with SLIME.

Standard shell

I switch between UNIX® and Windows environments and, although Emacs makes this switch a lot easier, I find it inconvenient having to use different Shell environments on different operating systems.

On Windows, the Cygwin tools provide a lot of the same tools that are available under UNIX® as well as a BASH shell. Alternatively, you might want to consider using eshell, a shell written in Emacs Lisp that comes as a standard feature in Emacs. If you use the given Emacs configuration, you can access eshell by pressing “F12”.

Using ACL tools with Emacs

I would like to use Emacs with Franz’s ACL but find that I use the Franz tools so much that I can’t afford to not load their IDE.

It doesn’t have to be an either/or decision. On Windows, Franz allows you to specify (under Options) that Emacs is to be the default editor in place of their built-in editor. On UNIX®, Emacs also works very well together with the Franz tools.*

Windows-style cut/copy/paste

I want to use Emacs on a Windows machine. Unfortunately, I have the Windows cut/copy/paste key bindings burned into my fingertips and would find it very difficult to switch back and forth between the Windows standard for these shortcut keys and the Emacs standard.

Luckily, you don’t have to! Download cua.el and you can continue to use the Windows defaults. In fact, you may find that the following commands in your .emacs file will make Emacs more Windows-like:

;; Windows-like mouse/arrow movement & selection (pc-selection-mode)
(delete-selection-mode t)
;; C-z=Undo, C-c=Copy, C-x=Cut, C-v=Paste (needs cua.el)
(require 'cua) (CUA-mode t)

Simplified Emacs setup

There was a lot of Emacs Lisp code presented in this paper. Do I really have to type in all this stuff to get started with Emacs and Lisp?

No, you can add yourself just what’s needed to get SLIME working.

You can try Portacle which has everything ready.

There is also a sample .emacs file that can be used to get started. It contains all of the configurations that have been described in this page and (hopefully) should work with some minor tweaking. See the CL-Cookbook page on “Setting up an IDE with Emacs on Windows or Mac OS X”.

Disclaimer

The original material on this page was originally presented at the ILC 2003 conference. A paper with more in-depth coverage of some of the material on this page can be found on Bill Clementson’s ILC2003 page, which is now archived.

It was edited in 2017.

Page source: emacs-ide.md


© 2002–2019 the Common Lisp Cookbook Project
T
O
C