hamacs/ha-programming-elisp.org

#+TITLE:  Emacs Lisp Configuration
#+AUTHOR: Howard X. Abrams
#+DATE:   2022-05-11

A literate programming file for configuring Emacs for Lisp programming.

#+begin_src emacs-lisp :exports none
  ;;; ha-lisp --- configuring Emacs for Lisp programming. -*- lexical-binding: t; -*-
  ;;
  ;; © 2022-2023 Howard X. Abrams
  ;;   Licensed under a Creative Commons Attribution 4.0 International License.
  ;;   See http://creativecommons.org/licenses/by/4.0/
  ;;
  ;; Author: Howard X. Abrams <http://gitlab.com/howardabrams>
  ;; Maintainer: Howard X. Abrams
  ;; Created: May 11, 2022
  ;;
  ;; This file is not part of GNU Emacs.
  ;;
  ;; *NB:* Do not edit this file. Instead, edit the original literate file at:
  ;;            /Users/howard.abrams/other/hamacs/ha-lisp.org
  ;;       And tangle the file to recreate this one.
  ;;
  ;;; Code:
  #+end_src
* Introduction
While I program in a lot of languages, I seem to be writing all my helper tools and scripts in … Emacs Lisp. I’m cranking this up to 11.

New, /non-literal/ source code comes from [[file:templates/emacs-lisp-mode.el][emacs-lisp-mode template]]:
#+begin_src emacs-lisp
  (ha-auto-insert-file (rx ".el" eol) "emacs-lisp-mode.el")
#+end_src
* Syntax Display
** Dim those Parenthesis
The [[https://github.com/tarsius/paren-face][paren-face]] project lowers the color level of parenthesis which I find better.

#+begin_src emacs-lisp
  (use-package paren-face
    :hook (emacs-lisp-mode . paren-face-mode))
#+end_src

Show code examples with the [[https://github.com/xuchunyang/elisp-demos][elisp-demos]] package.
#+begin_src emacs-lisp
  (use-package elisp-demos
    :config
    (advice-add 'describe-function-1 :after #'elisp-demos-advice-describe-function-1))
#+end_src
* Navigation and Editing
** Goto Definitions
Wilfred’s [[https://github.com/Wilfred/elisp-def][elisp-def]] project does a better job at jumping to the definition of a symbol at the point, so:
#+begin_src emacs-lisp
  (use-package elisp-def
    :hook (emacs-lisp-mode . elisp-def-mode))
#+end_src
This /should work/ with [[help:evil-goto-definition][evil-goto-defintion]], as that calls this list from [[help:evil-goto-definition-functions][evil-goto-definition-functions]]:
  - [[help:evil-goto-definition-imenu][evil-goto-definition-imenu]]
  - [[help:evil-goto-definition-semantic][evil-goto-definition-semantic]]
  - [[help:evil-goto-definition-xref][evil-goto-definition-xref]] … to show what calls a function
  - [[help:evil-goto-definition-search][evil-goto-definition-search]]

While I love packages that add functionality and I don’t have to learn anything, I’m running into an issue where I do a lot of my Emacs Lisp programming in org files, and would like to jump to the function definition /defined in the org file/. Since [[https://github.com/BurntSushi/ripgrep][ripgrep]] is pretty fast, I’ll call it instead of attempting to build a [[https://stackoverflow.com/questions/41933837/understanding-the-ctags-file-format][CTAGS]] table. Oooh, the =rg= takes a =—json= option, which makes it easier to parse.

#+begin_src emacs-lisp
  (defun ha-org-code-block-jump (str pos)
    "Go to a literate org file containing a symbol, STR.
  The POS is ignored."
    ;; Sometimes I wrap a function name in `=' characters, and these should be removed:
    (when (string-match (rx "=" (group (one-or-more any)) "=") str)
      (setq str (match-string 1 str)))
    (ignore-errors
      (let* ((default-directory (projectile-project-root))
             (command (format "rg --json '\\(def[^ ]+ %s ' *.org" str))
             (results (thread-last command
                                   shell-command-to-list
                                   second
                                   json-parse-string))
             (file    (thread-last results
                                   (gethash "data")
                                   (gethash "path")
                                   (gethash "text")))
             (line    (thread-last results
                                   (gethash "data")
                                   (gethash "line_number"))))
        (find-file file)
        (goto-line line))))

  (add-to-list 'evil-goto-definition-functions 'ha-org-code-block-jump)
#+end_src
And in case I need to call it directly:
#+begin_src emacs-lisp
  (defun ha-goto-definition ()
    (interactive)
    (evil-inner-WORD))
#+end_src
** Clever Parenthesis
We need to make sure we keep the [[https://github.com/Fuco1/smartparens][smartparens]] project always in /strict mode/, because who wants to worry about paren-matching:
#+begin_src emacs-lisp
  (use-package smartparens
    :custom
    (smartparens-global-strict-mode t)

    :config
    (sp-with-modes sp-lisp-modes
      ;; disable ', as it's the quote character:
      (sp-local-pair "'" nil :actions nil))

    (sp-with-modes (-difference sp-lisp-modes sp-clojure-modes)
      ;; use the pseudo-quote inside strings where it serve as hyperlink.
      (sp-local-pair "`" "'"
                     :when '(sp-in-string-p
                             sp-in-comment-p)
                     :skip-match (lambda (ms _mb _me)
                                   (cond
                                    ((equal ms "'") (not (sp-point-in-string-or-comment)))
                                    (t (not (sp-point-in-string-or-comment)))))))
    :hook
    (prog-mode . smartparens-strict-mode))
#+end_src

The [[https://github.com/luxbock/evil-cleverparens][evil-cleverparens]] solves having me create keybindings to the [[https://github.com/Fuco1/smartparens][smartparens]] project by updating the evil states with Lisp-specific bindings.
#+begin_src emacs-lisp
  (use-package evil-cleverparens
    :after smartparens
    :custom
    (evil-cleverparens-use-additional-bindings t)
    (evil-cleverparens-use-additional-movement-keys t)
    (evil-cleverparens-use-s-and-S t)

    :init
    (require 'evil-cleverparens-text-objects)

    :hook
    (prog-mode . evil-cleverparens-mode))  ;; All the languages!
    ;; Otherwise: (emacs-lisp-mode . evil-cleverparens-mode)
#+end_src

The /trick/ to being effective with the [[https://www.emacswiki.org/emacs/ParEdit][paredit-family]] of extensions is learning the keys. The killer “app” is the slurp/barf sequence. Use the ~<~ key, in normal mode, to barf (or jettison)… in other words, /move/ the paren closer to the point. For instance:
#+begin_src emacs-lisp :tangle no
  (+ 41 (* ‖1 3))  ⟹  (+ 41 (* ‖1) 3)
#+end_src
Use the ~>~ key to /slurp/ in outside objects into the current expression… in other words, move the paren away from the point. For instance:
#+begin_src emacs-lisp :tangle no
  (+ 41 (* ‖1) 3)  ⟹  (+ 41 (* ‖1 3))
#+end_src

*Opening Parens.* Those two keys seem straight-forward, but they behave differently when the are on the opening parens.
When the point (symbolized by ~‖~) is /on/ the opening paren, ~<~ moves the paren to the left. For instance:
#+begin_src emacs-lisp :tangle no
  (+ 41 ‖(* 1 3))  ⟹  (+ ‖(41 * 1 3))
#+end_src
And  the ~>~ moves the paren to the right. For instance:
#+begin_src emacs-lisp :tangle no
  (+ 41 ‖(* 1 3))  ⟹ (+ 41 * ‖(1 3))
#+end_src

I would like to have a list of what keybindings that work in =normal= mode:
- ~M-h~ / ~M-l~ move back/forward by functions
- ~H~ / ~L~ move back/forward by s-expression
- ~M-i~ insert at the beginning of the form
- ~M-a~ appends at the end of the form
- ~M-o~ new form after the current sexp
- ~M-O~ new form /before/ the current sexp
- ~M-j~ / ~M-k~ drags /thing at point/ and back and forth in the form
- ~>~ slurp forward if at the end of form, at beginning, it barfs backwards
- ~<~ slurp backward if at start of form, at the end, it barfs forwards
- ~M-(~ / ~M-)~ wraps next/previous form in parens (braces and brackets work too)
- ~x~ unwraps if the point is on the =(= of an expression.
- ~D~ deletes an entire s-expression, but this can depend on the position of the point.

The other advantage is moving around by s-expressions. This takes a little getting used to, for instance:
- ~[~ and ~]~ move from paren to paren, essentially, from s-expression.
- ~H~ and ~L~ act similarly to the above.
- ~(~ and ~)~ move up to the parent s-expression

We need a real-world example. Let’s suppose we entered this:
** Clever Keybindings
Adding a bunch of meta-key keybindings to the Normal state seems like I’m going backwards away from the /key sequences/ of Evil. First, adding frequently used (especially key movements) on the ~g~ key seems nice. Since I never bother with [[help:find-file-at-point][find-file-at-point]], I figured I could re-purpose that keybinding:

#+begin_src emacs-lisp :tangle no
(format "The sum of %d %d is %d" a b (+ a b))
  (use-package evil-cleverparens
    :general
    (:states 'normal :keymaps 'prog-mode-map
             "gf" '("evil cleverparens" . evil-cleverparens-hydra/body)
             "H" 'evil-cp-backward-sexp
             "L" 'ha-cp-forward-sexp))
#+end_src
But we forgot to define the =a= and =b= variables. One approach, after Escaping into the normal state, is to hit ~(~ to just to the beginning of the s-expression, and then type,  ~M-(~ to wrap the expression, and type ~i~ to go into insert mode:

For all the rest, why not make a Hydra using the pretty-hydra project:
#+begin_src emacs-lisp :tangle no
  (‖ (format "The sum of %d %d is %d" a b (+ a b)))
#+end_src
And now we can enter the =let= expression.
  (use-package pretty-hydra
    :after evil-cleverparens
    :config
    (pretty-hydra-define evil-cleverparens-hydra
      (:color red :quit-key "q")
      ("Movement"
       (("f" ha-cp-beginning-of-next-defun  "Next defun")
        ("C-f" evil-cp-end-of-defun nil)                  ; M-l
        ("F" evil-cp-beginning-of-defun     "Prev defun") ; M-h

        ("j" evil-cp-forward-symbol-begin   "Next symbol")
        ("k" evil-cp-backward-symbol-begin  "Prev symbol")
        ("J" evil-cp-forward-symbol-end     "Next symbol")
        ("K" evil-cp-backward-symbol-end    "Prev symbol"))

       "Move S-Exp"
       (("h" evil-cp-backward-sexp          "Prev s-exp")   ; H
        ("C-l" evil-cp-forward-sexp         nil)            ; L
        ("l" ha-cp-forward-sexp             "Next s-exp")

        ("C-u" evil-cp-backward-up-sexp     nil)
        ("u" ha-sp-up-sexp                  "Up s-exp")     ; See sp-up-sexp
        ("d" sp-down-sexp                   "Inside s-exp"))

       "Slurping"
       ((">" evil-cp->              "Barf")
        ("<" evil-cp-<              "Slurp")
        ("w" cp-wrap-round          "Wrap")
        ("b" evil-cp-drag-backward  "Drag Backward")      ; M-k
        ("g" evil-cp-drag-forward   "Drag forward"))      ; M-j

       "Manipulation"
       (("=" sp-indent-defun           "Indent defun")    ; M-q
        ("J" sp-join-sexp              "Join s-exp")      ; M-j
        ("s" sp-splice-sexp            "Splice s-exp")    ; M-s
        ("S" sp-split-sexp             "Split s-exp")     ; M-S
        ("t" sp-transpose-sexp         "Transpose s-exp") ; M-t
        ("T" sp-transpose-hybrid-sexp  "Transpose hybrid")
        ("x" sp-convolute-sexp         "Convolute s-exp") ; M-v
        ("r" sp-raise-sexp             "Raise s-exp"))    ; M-r

       "Insert"
       (("o" evil-cp-open-below-form  "After"  :color blue)
        ("O" evil-cp-open-above-form  "Before" :color blue)
        ("a" ha-cp-append-end         "append" :color blue)
        ("A" evil-cp-append           "Append" :color blue)
        ("i" evil-cp-insert           "Insert" :color blue))
       "Other"
       (("U" evil-undo           "Undo")
        ("R" evil-redo           "Redo")
        ("v" er/expand-region    "Expand")
        ("V" er/contract-region  "Contract")))))

Other nifty keybindings that I need to commit to muscle memory include:
| ~M-q~ | =sp-indent-defun=   |
| ~M-J~ | =sp-join-sexp=      |
| ~M-s~ | =sp-splice-sexp=    |
| ~M-S~ | =sp-split-sexp=     |
| ~M-t~ | =sp-transpose-sexp= |
| ~M-v~ | =sp-convolute-sexp= |
| ~M-r~ | =sp-raise-sexp=     |
  (defun ha-cp-beginning-of-next-defun (count)
    "Move to the beginning of the next function."
    (interactive "P")
    (evil-cp-end-of-defun count)
    (evil-cp-end-of-defun)
    (evil-cp-beginning-of-defun))

  (defun ha-sp-up-sexp (count)
    "Better opposite of `sp-down-sexp'."
    (interactive "P")
    (evil-cp-backward-up-sexp count)
    (evil-cp-backward-up-sexp)
    (sp-down-sexp))

  (defun ha-cp-forward-sexp (count)
    "Better opposite of `evil-cp-backward-sexp'."
    (interactive "P")
    (evil-cp-forward-sexp count)
    (evil-cp-forward-sexp)
    (evil-cp-backward-sexp))

  (defun ha-cp-append-end ()
    "Append to the end of the current s-expression."
    (interactive)
    (when (looking-at (rx (any "{" "(" "[")))
      (sp-down-sexp))
    (sp-end-of-sexp)
    (evil-cp-insert 1))

  (defun ha-cp-append-after ()
    "Append after the current s-expression."
    (interactive)
    (when (looking-at (rx (any "{" "(" "[")))
      (sp-down-sexp))
    (sp-end-of-sexp)
    (evil-cp-append 1))
#+end_src
** Eval Current Expression
The [[https://github.com/xiongtx/eros][eros]] package stands for Evaluation Result OverlayS for Emacs Lisp, and basically shows what each s-expression is near the cursor position instead of in the mini-buffer at the bottom of the window.
#+begin_src emacs-lisp
  (use-package eros
    :hook (emacs-lisp-mode . eros-mode))
#+end_src

A feature I enjoyed from Spacemacs is the ability to evaluate the s-expression currently containing the point. Not sure how they made it, but [[help:evil-cp-next-closing ][evil-cp-next-closing]] from cleverparens can help:

#+begin_src emacs-lisp
(defun ha-eval-current-expression ()
  "Evaluates the expression the point is currently 'in'.
It does this, by jumping to the end of the current
expression (using evil-cleverparens), and evaluating what it
finds at that point."
  (interactive)
  (save-excursion
    (evil-cp-next-closing)
    (evil-cp-forward-sexp)
    (call-interactively 'eval-last-sexp)))
#+end_src

And we just need to bind it.
#+begin_src emacs-lisp
  (ha-prog-leader
    "e c" '("current" . ha-eval-current-expression))
#+end_src
* Technical Artifacts                                :noexport:
Let's =provide= a name so we can =require= this file:

#+begin_src emacs-lisp :exports none
  (provide 'ha-programming-elisp)
  ;;; ha-programming-elisp.el ends here
  #+end_src

#+DESCRIPTION: configuring Emacs for Lisp programming.

#+PROPERTY:    header-args:sh :tangle no
#+PROPERTY:    header-args:emacs-lisp  :tangle yes
#+PROPERTY:    header-args    :results none :eval no-export :comments no mkdirp yes

#+OPTIONS:     num:nil toc:nil todo:nil tasks:nil tags:nil date:nil
#+OPTIONS:     skip:nil author:nil email:nil creator:nil timestamp:nil
#+INFOJS_OPT:  view:nil toc:nil ltoc:t mouse:underline buttons:0 path:http://orgmode.org/org-info.js