The Common Lisp Cookbook – Emacs

Table of Contents

The Common Lisp Cookbook – Emacs

🎉 Get the EPUB and PDF.

Using Emacs as an IDE

This page is meant to provide an introduction to using Emacs as a Lisp IDE.

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 fancy, contrib packages and other extensions

SLIME’s functionalities live in packages and so-called contrib modules must be loaded to add further functionalities. The default slime-fancy includes:

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:

Finding one’s way into Emacs’ built-in documentation

Emacs comes with built-in tutorials and documentation. Moreover, it is a self-documented and self-discoverable editor, capable of introspection to let you know about the current keybindings, to let you search about function documentation, available variables,source code, tutorials, etc. Whenever you ask yourself questions like “what are the available shortcuts to do x” or “what does this keybinding really do”, the answer is most probably a keystroke away, right inside Emacs. You should learn a few keybindings to be able to discover Emacs with Emacs flawlessly.

The help on the topic is here:

The help keybindings start with either C-h or F1. Important ones are:

Some Emacs packages give even more help.

More help and discoverability packages

Sometimes, you start typing a key sequence but you can’t remember it completely. Or, you wonder what other keybindings are related. Comes which-key-mode. This packages will display all possible keybindings starting with the key(s) you just typed.

For example, I know there are useful keybindings under C-x but I don’t remember which ones… I just type C-x, I wait for half a second, and which-key shows all the ones available.

Just try it with C-h too!

See also Helpful, an alternative to the built-in Emacs help that provides much more contextual information.

Learn Emacs with the built-in tutorial

Emacs ships its own tutorial. You should give it a look to learn the most important keybindings and concepts.

Call it with M-x help-with-tutorial (where M-x is alt-x).

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

Emacs has, of course, built-in commands to deal with s-expressions.

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

Use C-M-f and C-M-b (forward-sexp and backward-sexp) to move in units of s-expressions.

Use 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

Use C-M-@ to highlight an entire sexp. Then press C-M-u to expand the selection “upwards” and C-M-d to move forward down one level of parentheses.

Deleting s-expressions

Use C-M-k (kill-sexp) and C-M-backspace (backward-kill-sexp) (but caution: this keybinding may restart the system on GNU/Linux).

For example, if point is before (progn (I’ll use [] as an indication where the cursor is):

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

and you press C-M-k, you get:

(defun d ()
  (if t
      (+ 3 3)
      []
      (+ 4 4)))
Indenting s-expressions

Indentation is automatic for Lisp forms.

Pressing TAB will indent incorrectly indented code. For example, put the point at the beginning of the (+ 3 3) form and press TAB:

(progn
(+ 3 3))

you correctly get

(progn
  (+ 3 3))

Use C-M-q (slime-reindent-defun) to indent the current function definition:

;; 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 (now correctly indented)."
  (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))))))

You can also select a region and call M-x indent-region.

Support for parenthesis

Use M-( to insert a pair of parenthesis (()), M-x check-parens to spot malformed sexps, C-u <n> M-( to enclose sexps with parens, and C-c C-] (slime-close-all-parens-in-sexp) to insert the required number of closing parenthesis.

For example (point is before the parenthesis):

|(- 2 2)
;; Press C-u 1 M-( to enclose it with parens:
(|(- 2 2))
Code completion

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

In the REPL, it’s simply TAB.

Use Emacs’ hippie-expand, bound to M-/, to complete any string present in other open buffers.

Hiding/showing code

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

See also code folding.

Comments

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

Evaluating and Compiling Lisp in SLIME

Compile the entire buffer by pressing C-c C-k (slime-compile-and-load-file).

Compile a region with M-x slime-compile-region.

Compile a defun by putting the cursor inside it and pressing C-c C-c (slime-compile-defun).

To evaluate rather than compile:

See also other commands in the menu.

EVALUATION VS COMPILATION

There are a couple of pragmatic differences when choosing between compiling or evaluating. In general, it is better to compile top-level forms, for two reasons:

eval is still useful to observe results from individual non top-level forms. For example, say you have this function:

(defun foo ()
  (let ((f (open "/home/mariano/test.lisp")))
    ...))

Go to the end of the OPEN expression and evaluate it (C-x C-e), to observe the result:

=> #<SB-SYS:FD-STREAM for "file /mnt/e6b00b8f-9dad-4bf4-bd40-34b1e6d31f0a/home/marian/test.lisp" {1003AAAB53}>

Or on this example, with the cursor on the last parentheses, press C-x C-e to evaluate the let:

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

You should see numbers printed in the REPL.

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

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)

Use M-x grep, rgrep, occur…

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

Go to definition

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

Go to symbol, list symbols in current source

Use C-u M-. (slime-edit-definition with a prefix argument, also available as M-- M-.) to autocomplete the symbol and navigate to it. This command always asks for a symbol even if the cursor is on one. It works with any loaded definition. Here’s a little demonstration video.

You can think of it as a imenu completion that always work for any Lisp symbol. Add in Slime’s fuzzy completion for maximum powerness!

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

Slime has nice cross-referencing facilities. For example, you can ask what calls a particular function, what expands a macro, or where a global variable is being used.

Results are presented in a new buffer, listing the places which reference a particular entity. From there, we can press Enter to go to the corresponding source line, or more interestingly we can recompile the place at point by pressing C-c C-c on that line. Likewise, C-c C-k will recompile all the references. This is useful when modifying macros, inline functions, or constants.

The bindings are the following (they 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.

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

The main shortcut to know is:

Other bindings which may be useful:

You can enhance the help buffer with the Slime extension slime-doc-contribs. It will show more information in a nice looking buffer.

Inspect

You can call (inspect 'symbol) from the REPL or call it with C-c I from a source file.

Macroexpand

Use C-c M-m to macroexpand a macro call

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)

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.

Searching Quicklisp libraries

From the REPL, we can use ,ql to install a package known by name already.

In addition, we can use the Quicklisp-systems Slime extension to search, browse and load Quicklisp systems from 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.

Default cut/copy/paste keybindings

I am so used to C-c, C-v and friends to copy and paste text that the default Emacs shortcuts don’t make any sense to me.

Luckily, you have a solution! Install cua-mode and you can continue to use these shortcuts.

;; C-z=Undo, C-c=Copy, C-x=Cut, C-v=Paste (needs cua.el)
(require 'cua) (CUA-mode t)

Appendix

All Slime REPL shortcuts

Here is the reference of all Slime shortcuts that work in the REPL.

To see them, go in a REPL, type C-h m and go to the Slime REPL map section.

REPL mode defined in ‘slime-repl.el’:
Major mode for interacting with a superior Lisp.
key             binding
---             -------

C-c             Prefix Command
C-j             slime-repl-newline-and-indent
RET             slime-repl-return
C-x             Prefix Command
ESC             Prefix Command
SPC             slime-space
  (that binding is currently shadowed by another mode)
,               slime-handle-repl-shortcut
DEL             backward-delete-char-untabify
<C-down>        slime-repl-forward-input
<C-return>      slime-repl-closing-return
<C-up>          slime-repl-backward-input
<return>        slime-repl-return

C-x C-e         slime-eval-last-expression

C-c C-c         slime-interrupt
C-c C-n         slime-repl-next-prompt
C-c C-o         slime-repl-clear-output
C-c C-p         slime-repl-previous-prompt
C-c C-s         slime-complete-form
C-c C-u         slime-repl-kill-input
C-c C-z         other-window
C-c ESC         Prefix Command
C-c I           slime-repl-inspect

M-RET           slime-repl-closing-return
M-n             slime-repl-next-input
M-p             slime-repl-previous-input
M-r             slime-repl-previous-matching-input
M-s             previous-line

C-c C-z         run-lisp
  (that binding is currently shadowed by another mode)

C-M-x           lisp-eval-defun

C-M-q           indent-sexp

C-M-q           prog-indent-sexp
  (that binding is currently shadowed by another mode)

C-c M-e         macrostep-expand
C-c M-i         slime-fuzzy-complete-symbol
C-c M-o         slime-repl-clear-buffer

All other Slime shortcuts

Here are all the default keybindings defined by Slime mode.

To see them, go in a .lisp file, type C-h m and go to the Slime section.

Commands to compile the current buffer’s source file and visually
highlight any resulting compiler notes and warnings:
C-c C-k	- Compile and load the current buffer’s file.
C-c M-k	- Compile (but not load) the current buffer’s file.
C-c C-c	- Compile the top-level form at point.

Commands for visiting compiler notes:
M-n	- Goto the next form with a compiler note.
M-p	- Goto the previous form with a compiler note.
C-c M-c	- Remove compiler-note annotations in buffer.

Finding definitions:
M-.
- Edit the definition of the function called at point.
M-,
- Pop the definition stack to go back from a definition.

Documentation commands:
C-c C-d C-d	- Describe symbol.
C-c C-d C-a	- Apropos search.
C-c M-d	- Disassemble a function.

Evaluation commands:
C-M-x	- Evaluate top-level from containing point.
C-x C-e	- Evaluate sexp before point.
C-c C-p	- Evaluate sexp before point, pretty-print result.

Full set of commands:
key             binding
---             -------

C-c             Prefix Command
C-x             Prefix Command
ESC             Prefix Command
SPC             slime-space

C-c C-c         slime-compile-defun
C-c C-j         slime-eval-last-expression-in-repl
C-c C-k         slime-compile-and-load-file
C-c C-s         slime-complete-form
C-c C-y         slime-call-defun
C-c ESC         Prefix Command
C-c C-]         slime-close-all-parens-in-sexp
C-c x           slime-export-symbol-at-point
C-c ~           slime-sync-package-and-default-directory

C-M-a           slime-beginning-of-defun
C-M-e           slime-end-of-defun
M-n             slime-next-note
M-p             slime-previous-note

C-M-,           slime-previous-location
C-M-.           slime-next-location

C-c TAB         completion-at-point
C-c RET         slime-expand-1
C-c C-p         slime-pprint-eval-last-expression
C-c C-u         slime-undefine-function
C-c ESC         Prefix Command

C-c C-b         slime-interrupt
C-c C-d         slime-doc-map
C-c C-e         slime-interactive-eval
C-c C-l         slime-load-file
C-c C-r         slime-eval-region
C-c C-t         slime-toggle-fancy-trace
C-c C-v         Prefix Command
C-c C-w         slime-who-map
C-c C-x         Prefix Command
C-c C-z         slime-switch-to-output-buffer
C-c ESC         Prefix Command
C-c :           slime-interactive-eval
C-c <           slime-list-callers
C-c >           slime-list-callees
C-c E           slime-edit-value
C-c I           slime-inspect

C-x C-e         slime-eval-last-expression
C-x 4           Prefix Command
C-x 5           Prefix Command

C-M-x           slime-eval-defun
M-,             slime-pop-find-definition-stack
M-.             slime-edit-definition
M-?             slime-edit-uses
M-_             slime-edit-uses

C-c M-c         slime-remove-notes
C-c M-e         macrostep-expand
C-c M-i         slime-fuzzy-complete-symbol
C-c M-k         slime-compile-file
C-c M-q         slime-reindent-defun

C-c M-m         slime-macroexpand-all

C-c C-v C-d     slime-describe-presentation-at-point
C-c C-v TAB     slime-inspect-presentation-at-point
C-c C-v C-n     slime-next-presentation
C-c C-v C-p     slime-previous-presentation
C-c C-v C-r     slime-copy-presentation-at-point-to-repl
C-c C-v C-w     slime-copy-presentation-at-point-to-kill-ring
C-c C-v ESC     Prefix Command
C-c C-v SPC     slime-mark-presentation
C-c C-v d       slime-describe-presentation-at-point
C-c C-v i       slime-inspect-presentation-at-point
C-c C-v n       slime-next-presentation
C-c C-v p       slime-previous-presentation
C-c C-v r       slime-copy-presentation-at-point-to-repl
C-c C-v w       slime-copy-presentation-at-point-to-kill-ring
C-c C-v C-SPC   slime-mark-presentation

C-c C-w C-a     slime-who-specializes
C-c C-w C-b     slime-who-binds
C-c C-w C-c     slime-who-calls
C-c C-w RET     slime-who-macroexpands
C-c C-w C-r     slime-who-references
C-c C-w C-s     slime-who-sets
C-c C-w C-w     slime-calls-who
C-c C-w a       slime-who-specializes
C-c C-w b       slime-who-binds
C-c C-w c       slime-who-calls
C-c C-w d       slime-who-depends-on
C-c C-w m       slime-who-macroexpands
C-c C-w r       slime-who-references
C-c C-w s       slime-who-sets
C-c C-w w       slime-calls-who

C-c C-d C-a     slime-apropos
C-c C-d C-d     slime-describe-symbol
C-c C-d C-f     slime-describe-function
C-c C-d C-g     common-lisp-hyperspec-glossary-term
C-c C-d C-p     slime-apropos-package
C-c C-d C-z     slime-apropos-all
C-c C-d #       common-lisp-hyperspec-lookup-reader-macro
C-c C-d a       slime-apropos
C-c C-d d       slime-describe-symbol
C-c C-d f       slime-describe-function
C-c C-d g       common-lisp-hyperspec-glossary-term
C-c C-d h       slime-documentation-lookup
C-c C-d p       slime-apropos-package
C-c C-d z       slime-apropos-all
C-c C-d ~       common-lisp-hyperspec-format
C-c C-d C-#     common-lisp-hyperspec-lookup-reader-macro
C-c C-d C-~     common-lisp-hyperspec-format

C-c C-x c       slime-list-connections
C-c C-x n       slime-next-connection
C-c C-x p       slime-prev-connection
C-c C-x t       slime-list-threads

C-c M-d         slime-disassemble-symbol
C-c M-p         slime-repl-set-package

C-x 5 .         slime-edit-definition-other-frame

C-x 4 .         slime-edit-definition-other-window

C-c C-v M-o     slime-clear-presentations

See also

Page source: emacs-ide.md

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