spacemacs/layers/+lang/common-lisp/README.org

#+TITLE: Common Lisp layer

#+TAGS: dsl|layer|lisp|programming

[[file:img/slime.png]]

* Table of Contents                     :TOC_5_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
- [[#structuraly-safe-editing][Structuraly safe editing]]
- [[#key-bindings][Key bindings]]
  - [[#working-with-lisp-files-barfage-slurpage--more][Working with lisp files (barfage, slurpage & more)]]
  - [[#leader][Leader]]
    - [[#help][Help]]
    - [[#evaluation][Evaluation]]
    - [[#repl][REPL]]
    - [[#compile][Compile]]
    - [[#navigation][Navigation]]
    - [[#macroexpansion][Macroexpansion]]

* Description
This layer provides support for Common Lisp to Spacemacs.

** Features:
- Syntax highlighting
- Auto-completion using company
- Repl support via [[https://github.com/slime/slime][SLIME]]
- Support for specific lisp navigation styles via =common-lisp-mode=
- Support for [[http://www.sbcl.org/][sbcl]] backend or any other =common-lisp= implementation

* Install
If you have previously installed slime in any other way, it is recommended that
you uninstall it before proceeding. You should clean up any config files tied to
slime that are left behind as well. Linux users can just purge the slime package
if it was a distribution install.

To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =common-lisp= to the existing =dotspacemacs-configuration-layers= list in this
file.

This layer defaults to using [[http://www.sbcl.org/][sbcl]]. If you want to use a different implementation
of Common Lisp, you can specify it in your =~/.spacemacs=

#+BEGIN_SRC emacs-lisp
  (defun dotspacemacs/user-config ()
    (setq inferior-lisp-program "/path/to/your/lisp"))
#+END_SRC

* Structuraly safe editing
This layer adds support for =evil-cleverparens= which allows to safely edit
lisp code by keeping the s-expressions balanced.

By default this mode is not activated. You can turn it on locally on the active
buffer with ~SPC m T s~ (=s= for safe).

To turn it on automatically for all =common-lisp= buffers call the following
function in your =dotspacemacs/user-config= function:

#+BEGIN_SRC emacs-lisp
  (spacemacs/toggle-evil-safe-lisp-structural-editing-on-register-hook-common-lisp-mode)
#+END_SRC

or to enable it for all supported modes:

#+BEGIN_SRC emacs-lisp
  (spacemacs/toggle-evil-safe-lisp-structural-editing-on-register-hooks)
#+END_SRC

When enabled the symbol =🆂= should be displayed in the mode-line.

* Key bindings
** Working with lisp files (barfage, slurpage & more)
Spacemacs comes with a special =lisp-state= for working with lisp code that
supports slurpage, barfage and more tools you'll likely want when working with
lisp.

As this state works the same for all files, the documentation is in global
[[https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.org#lisp-key-bindings][DOCUMENTATION.org]]. In general, use ~SPC k~ to interact with the lisp-state.

** Leader
*** Help

| Key binding | Description                                             |
|-------------+---------------------------------------------------------|
| ~SPC m h a~ | SLIME apropos                                           |
| ~SPC m h d~ | Disassemble symbol at point                             |
| ~SPC m h h~ | Describe symbol at point                                |
| ~SPC m h i~ | Inspect definition                                      |
| ~SPC m h H~ | Hyperspec lookup symbol at point                        |
| ~SPC m h p~ | Browse apropos results for a package's exported symbols |
| ~SPC m h t~ | Toggle tracing of the function at point                 |
| ~SPC m h T~ | Untrace all functions                                   |
| ~SPC m h <~ | Show all known callers                                  |
| ~SPC m h >~ | Show all known callees                                  |
| ~SPC m h m~ | Show all usages of a macro                              |
| ~SPC m h r~ | Show references to global variable                      |
| ~SPC m h s~ | Show all methods specialized on a class                 |

*** Evaluation

| Key binding | Description                                       |
|-------------+---------------------------------------------------|
| ~SPC m e b~ | Evaluate buffer                                   |
| ~SPC m e c~ | Evaluate parent sexp of current form around point |
| ~SPC m e C~ | Evaluate current =def= or =set= form around point |
| ~SPC m e e~ | Evaluate last sexp                                |
| ~SPC m e l~ | Go to end of line and evaluate last sexp          |
| ~SPC m e f~ | Evaluate top level sexp                           |
| ~SPC m e F~ | Undefine the function at point                    |
| ~SPC m e r~ | Evaluate region                                   |
| ~SPC m e s~ | Evaluate symbol around point                      |

*** REPL

| Key binding | Description                      |
|-------------+----------------------------------|
| ~SPC m s i~ | Start an inferior process        |
| ~SPC m s e~ | Evaluate last expression in REPL |
| ~SPC m s q~ | Quit                             |

*** Compile

| Key binding | Description              |
|-------------+--------------------------|
| ~SPC m c c~ | Compile file             |
| ~SPC m c C~ | Compile file and load it |
| ~SPC m c l~ | Load file                |
| ~SPC m c n~ | Remove compilation notes |
| ~SPC m c f~ | Compile function         |
| ~SPC m c r~ | Compile region           |

*** Navigation

| Key binding               | Description      |
|---------------------------+------------------|
| ~SPC m g g~               | Go to definition |
| ~SPC m g b~               | Go back          |
| ~SPC m g n~               | Next note        |
| ~SPC m g N~ or ~SPC m g p | Previous note    |

*** Macroexpansion

| Key binding | Description                                   |
|-------------+-----------------------------------------------|
| ~SPC m m a~ | Macroexpand the expression at point completly |
| ~SPC m m o~ | Macroexpand the expression at point once      |