151 lines
6.6 KiB
Org Mode
151 lines
6.6 KiB
Org Mode
#+TITLE: Emacs Lisp layer
|
||
|
||
[[file:img/emacs.png]]
|
||
|
||
* Table of Contents :TOC_4_gh:noexport:
|
||
- [[#description][Description]]
|
||
- [[#features][Features:]]
|
||
- [[#install][Install]]
|
||
- [[#auto-compile][Auto-compile]]
|
||
- [[#working-with-lisp-files-barfage-slurpage--more][Working with lisp files (barfage, slurpage & more)]]
|
||
- [[#debugging-elisp][Debugging Elisp]]
|
||
- [[#key-bindings][Key bindings]]
|
||
- [[#additional-evaluation-functions][Additional evaluation functions]]
|
||
- [[#format-code][Format code]]
|
||
- [[#debugging][Debugging]]
|
||
|
||
* Description
|
||
This layer gathers all the configuration related to emacs-lisp. This should
|
||
always be in your dotfile, it is not recommended to uninstall it.
|
||
|
||
** Features:
|
||
- Auto-completion using company
|
||
- Linting using flycheck integration
|
||
- Repl support via =IELM=
|
||
- Support for specific lisp navigation styles via =emacs-lisp-mode=
|
||
- Auto-compile via [[https://github.com/tarsius/auto-compile][auto-compile]] package
|
||
- Debuggin via [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Edebug.html#Edebug][edebug]]
|
||
|
||
* Install
|
||
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
|
||
add =emacs-lisp= to the existing =dotspacemacs-configuration-layers= list in this
|
||
file.
|
||
|
||
* Auto-compile
|
||
This layer adds the [[https://github.com/tarsius/auto-compile][auto-compile]] package to automatically keep the byte-compiled
|
||
version of your Emacs lisp files synced with the uncompiled version on every
|
||
save. If there are any compiler errors in the file, you will see a counter show
|
||
up in the mode line. You can hover over these numbers to get a description or
|
||
view the compiler output with the ~SPC m c l~ key binding. To disable the
|
||
feature use this line in your =dotspacemacs/user-config= function.
|
||
|
||
#+BEGIN_SRC emacs-lisp
|
||
(remove-hook 'emacs-lisp-mode-hook 'auto-compile-mode)
|
||
#+END_SRC
|
||
|
||
You can also exclude the =auto-compile= package.
|
||
|
||
* 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.
|
||
|
||
* Debugging Elisp
|
||
Here is an interactive quick start to debug Emacs Lisp.
|
||
|
||
First you need to read this file in Emacs in order to have the following code
|
||
block to be interactively opened as Emacs Lisp.
|
||
|
||
#+BEGIN_SRC elisp
|
||
(defun helloworld (name)
|
||
(let ((n (subroutine name)))
|
||
(message (format "Hello world, %s!" name))))
|
||
|
||
(defun subroutine (s)
|
||
(concat "my dear " s))
|
||
|
||
(helloworld "Spacemacs")
|
||
#+END_SRC
|
||
|
||
1) To start the tutorial put your point in the source block above and press ~, '~
|
||
it will open a new buffer in =emacs-lisp-mode=.
|
||
|
||
2) Evaluate each sexp by putting your point in each of them and press ~, e f~.
|
||
|
||
3) To debug the =helloworld= function, put your cursor on the =defun= keyword and
|
||
press ~SPC m d f~ (or ~, d f~), it will put a breakpoint on the function (we say
|
||
that we instrumentalise this function) so whenever the Lisp interpreter
|
||
encounters this function it will start the debugger.
|
||
|
||
4) Then go to the closing parenthesis of =(helloworld "Spacemacs")= and press
|
||
~, e e~ to evaluate it, if you are using =vim= editing style you end up in
|
||
evilified state otherwise you end up in emacs state and =*Debugging*= is
|
||
displayed in the mode line.
|
||
|
||
5) Press ~s~ to go to next step up to the opening parenthesis of
|
||
=(subroutine name)=,
|
||
|
||
6) Press ~i~ to go into the =subroutine= where you can press ~s~ to step in
|
||
function or press ~o~ to go out of it.
|
||
|
||
7) Press ~a~ to stop debugging.
|
||
|
||
* Key bindings
|
||
|
||
| Key Binding | Description |
|
||
|----------------------------+--------------------------------------------------------|
|
||
| ~SPC m g g~ | go to definition of symbol under point |
|
||
| ~SPC m g G~ | go to definition of symbol under point in other window |
|
||
| ~SPC m h h~ | describe symbol at point |
|
||
| ~SPC m c c~ | byte compile the current file |
|
||
| ~SPC m c l~ | popup compile-log buffer |
|
||
| ~SPC m e $~ or ~SPC m e l~ | go to end of current line and evaluate |
|
||
| ~SPC m e b~ | evaluate current buffer |
|
||
| ~SPC m e C~ | evaluate current =defun= or =setq= |
|
||
| ~SPC m e e~ | evaluate sexp before point |
|
||
| ~SPC m e f~ | evaluation current function |
|
||
| ~SPC m e r~ | evaluate current region |
|
||
| ~SPC m ,~ | toggle =lisp state= |
|
||
| ~SPC m t b~ | run tests of current buffer |
|
||
| ~SPC m t q~ | run =ert= |
|
||
| ~SPC m d m~ | open [[https://github.com/joddie/macrostep][macrostep]] transient-state |
|
||
|
||
** Additional evaluation functions
|
||
If =smartparens= is used the following additional key bindings are available:
|
||
|
||
| Key Binding | Description |
|
||
|-------------+------------------------------|
|
||
| ~SPC m e c~ | evaluate sexp around point |
|
||
| ~SPC m e s~ | evaluate symbol around point |
|
||
|
||
** Format code
|
||
The [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/%2Bemacs/semantic/README.org][semantic]] layer should be installed for these key bindings to become active.
|
||
|
||
| Key Binding | Description |
|
||
|-------------+-------------------------|
|
||
| ~SPC m = b~ | format current buffer |
|
||
| ~SPC m = f~ | format current function |
|
||
| ~SPC m = o~ | format all on one line |
|
||
| ~SPC m = s~ | format current sexp |
|
||
|
||
** Debugging
|
||
To start debugging:
|
||
|
||
| Key Binding | Description |
|
||
|-------------+------------------------------------------------------------------------|
|
||
| ~SPC m d f~ | on a =defun= symbol toggle on the instrumentalisation of the function |
|
||
| ~SPC m d F~ | on a =defun= symbol toggle off the instrumentalisation of the function |
|
||
| ~SPC m d t~ | insert =(debug)= to print the stack trace and re-evaluate the function |
|
||
|
||
In =edebug-mode= (=*Debugging*= is displayed in the minor modes segment of the
|
||
mode line)
|
||
|
||
TODO
|
||
|
||
In =debugger-mode= (=Debugger= is displayed in major mode segment of the mode
|
||
line)
|
||
|
||
TODO
|