/evil-lispy

precision Lisp editing with Evil and Lispy

Primary LanguageEmacs Lisp

./img/EvilLogo.png ./img/lispy-logo.png

https://travis-ci.org/sp3ctum/evil-lispy.svg?branch=master http://melpa.org/packages/evil-lispy-badge.svg

This package integrates the excellent lispy lisp editing package to Evil. Lispy works with different lisp modes, like Emacs Lisp and Clojure (and others!).

Goals and design philosophy

The goal is to encourage a workflow where you use the standard evil-mode for general editing, and enter evil-lispy-mode to make structural edits using lispy bindings.

Here is a sales pitch of what this mode thinks is best for you:

  • Lisp has a natural structure
    • Natural to edit structurally
    • Natural to navigate structurally
  • You will want to use structural editing when possible, and fallback to familiar Evil commands.
    • With evil-lispy, use hjkl for moving, C-SPC (control+space) to select, e to eval. Intuitive for Evil / vim users. You now know the basics!
  • Natural and easy fallback to vanilla Evil editing
    • If you panic, just hit ESC to return to normal mode
    • You can still use e.g. Evil () text objects just fine. When you learn more of lispy, your productivity will only increase.
  • Modal editing is good for your health
    • Lispy commands only apply when explicitly activated
    • Less chance of munging your code unexpectedly

Lispy has great power, and while it comes at the cost of a lot of key bindings, you can get started with just a few. To this end, evil-lispy provides cheat sheets, such as this one for navigation commands:

./img/navigation-cheat-sheet.png

You can access these with f1 while in evil-lispy-state. Read on for more information.

Installation

Available from MELPA.

;; M-x package-install evil-lispy

;; in your config, load the code with e.g. require
(require 'evil-lispy)

;; make evil-lispy start in the modes you want
(add-hook 'emacs-lisp-mode-hook #'evil-lispy-mode)
(add-hook 'clojure-mode-hook #'evil-lispy-mode)

Key Bindings

To learn lispy, I suggest you see these things in order:

All lispy structural editing commands are available when evil-lispy-mode is activated. So to use these commands, you must first enter evil-lispy-mode.

Normal mode

Enter evil-lispy-mode mode from normal mode with the following commands:

Key BindingDescription
(jump to the previous parenthesis and enter evil-lispy-mode
)same, but jump to the next parenthesis instead
C-SPCselect current symbol/expression and enter evil-lispy-mode
<iinsert at the start, inside, like so: ($ foo)
>Ainsert at the end, inside, like so: (foo $)

Other special functionality only available in normal mode:

Key BindingDescription
KDescribe function inline (not available in all lisp modes)
Control-1Same thing
Control-2Display argument list (not available in all lisp modes)

Visual mode

You can select anything in evil-visual-mode and use these commands:

Key BindingDescription
RETManipulate the selection with lispy-mode

Insert mode

Reminder: In standard insert-mode, you can write any characters normally. Only when you explicitly activate evil-lispy-mode, lispy commands become available.

These special bindings are active in insert mode:

Key BindingDescription
}Insert [ ] brackets
)Jump out of the current sexp (to the right), enter lispy-mode
[ and ]Jump out of the current sexp (to the left / right), enter lispy-mode
;Comment entire line, or end of line. Toggles autoload comments for elisp too.

Changes to lispy

These bindings are different from vanilla lispy:

iGo in the current expression, or move past it if not possible
ffix indentation of the current expression
oSwitch to the other side of the current expression or selection
dDrag the current expression with the next hjkl
f1Display a cheat sheet for the most commonly used commands

Miscellaneous

In lispy, using C-u 2j will go down two sexps. To get the same thing in evil-lispy, you can use 2j, just like in evil/vim.

Credits

Forked from bcarrell/evil-lispy. Many, many thanks to bcarrell for his awesome work on this.