lispy 0.21.0 is out19 Jan 2015
The last release was more than a month ago, and there have been more than 130 commits to master since then. Somehow, I've been dragging my feet with this release: the (3 pages of) release notes were in the draft stage for 10 days now, while I kept committing on top of them.
This project is my vision of efficient LISP editing. According to Github, I started it more than a year ago, although the initial commit already contained around 1000 lines of code. After a year, it's more than 100 interactive commands in 5000 lines of code and 1000 lines of tests.
Initially, I started the project because, while I wanted to learn
Paredit to get more efficient, I did not want to learn Paredit's
cumbersome bindings. Having established a skeleton that allows to call
Paredit-like commands with plain letters, over time, I've tacked on
anything LISP-related here. In this way, it's very similar to
org-mode, which starts with an outline and TODO skeleton, and then
adds everything else in the world on top of that. Heck, I actually
org-mode's outline features on top of
lispy: when at an
outline, i is equivalent to
org-mode's TAB, and
I is equivalent to S-tab.
Among the other packages with which
Main idea behind
The idea is to have plain letters, like h or r, call commands instead of self-inserting, but only if the point position is such that you wouldn't want to self-insert anyway. When this situation occurs, I like to say "the point is special"; this shortcut is all over the code and the docs.
This is a bit similar to
vi's normal/insert states, but instead of
"holding" the current state in your head, it's visible through just
the point position. And instead of having just the
Esc/i combination to toggle normal/insert state,
you can do it with any command that moves point,
e.g. C-f, or C-a, or even any custom command
that you write.
lispy does provide [, ], and
C-3 key bindings for getting into special, but you are free
to use any other binding or command that you want.
For instance, starting from this code and point position (which is already special):
(when (= arg 0)
(setq arg 2000))
you can move to the
when statement with h (
(when (= arg 0) (setq arg 2000))
or you can remove the
when statement altogether with r (
(setq arg 2000)
or you can:
(setq arg 2000)statement with e (
lispy-eval); the result will be displayed in the echo area; works for multiple LISP dialects
- evaluate and insert with E (
lispy-eval-and-insert); the actual value
2000will be inserted below the expression
- evaluate and replace with xr (
lispy-eval-and-replace); the expression will be replaced with
- copy the statement to the kill ring with n (
- delete the statement with C-d (
- insert a copy of the statement below with c (
- insert 3 copies of the statement below with 3c (
- move the statement on the previous line with DEL (
- mark the statement with m (
- mark only
argwith 2m (
- get help for
setqwith xh (
- get help for
argwith 2mxh (
2000to kill ring with 3mn (
- move the statement outside of
whenwith oh (
(= arg 0)with
(setq arg 2000)with w (
- move it back with s (
- put the whole
whenexpression on one line with hO (
- narrow the buffer to current sexp with N (
- widen the buffer with W (
- a lot of other things, there are 52 plain letters, after all
Note that in the following code, the point is not special:
en (= arg 0) (setq arg 2000))
so if you would type h, it would not call
lispy-left, but would insert "h" instead, yielding
- to get the point into special before
(when, you can use either C-a or [ or C-M-a
- to get the point into special after
arg 0), you can use either C-e or ]
- to get the point into special after
2000)), you can use C-3
Evolution of special
Initially, the special state was only for the point before an open paren or after a close paren, since you almost never-ever want to insert characters at those positions. Over time, other point states were added to special:
- region is active (supersedes expand-region for LISP dialects)
- the point is at the start of a comment
- the point is at the start of an outline
Region selection is especially important, since it is super-useful for manipulating (move, copy, eval, get-help, goto-definition) symbols inside lists. Since these symbols aren't delimited with parens, the only way to get to them with special is though region selection.
Happily, region selection will fix the largest source of Paredit
unbalanced paren errors: while using
commands, you can't copy an unbalanced expression, and thus you can't
yank an unbalanced expression. You just have to use m and
M-m instead of C-SPC; and h,
j, k, l, i,
>, and < instead of e.g. C-f and
Since there are only 26 lower-case letters and 26 upper-case letters,
the state of the command bindings in
lispy quickly turned into
survival of the fittest:
- the commands that were used the most got the priority bindings of lower case letters on the home row
- the second tier got the other lower-case bindings
- the third tier of commands were put on upper-case letters and on x + lower-case letters
- the fourth tier of commands are not bound at all, and I'm considering to obsolete some of them, just to keep things simpler.
ADD: the Annoyance-Driven Development
The other part of evolving and refining the commands, consisted of noticing small annoyances for when some generic command wasn't working as intended, or it was working in a sub-optimal way in a certain situation. After this, I would fix the command and put a test on it, to make sure that the annoyance does not surface in the future.
Notes on LISP dialects
My priority is Elisp, since that's what I'm using to implement
lispy, but the following dialects are also supported:
To be supported, all a LISP dialect needs is just to use
[ as the opening delimiter; and
] as the closing
delimiter, no actual adaptations in the
lispy code are necessary.
The only thing that needs to be implemented on a per-dialect basis is the language-specific eval:
- e (
- E (
- xr (
- xj (
Also, though the jump-to-definition functionality could be implemented
via CEDET, environments like SLIME can do it much better, so
lispy-follow) and M-. (
lispy-goto-symbol) use the
appropriate environment's facilities. Somehow, I still haven't managed
to implement this for Geiser.
Drinking from the
lispy fire hose
In the screenshot above, I start with the code and point position on
the top. Then, after typing miji, I should end up with the
state below: the point and mark position have moved. In this
particular situation, I could follow-up with e to see the
auto-mode-alist. Here's how to decipher miji:
- m -
lispy-mark-list: marks current expression
- i -
lispy-tab(mnemonic for indent or inner): marks the
carof current expression
- j -
lispy-down(vi shortcut to move down): moves the point and mark down by one sexp, selecting the quoted expression
- i -
lispy-tab: selects the
carof the quoted expression, i.e.
As you see from the screenshot, I have
on. It's even on in the tests visualization!
The most basic
lispy commands: the arrows
- h is left
- j is down
- k is up
- l is right
The directions are literal only if you have your code properly indented, with newlines after each sexp. Otherwise, it may be the case that j moves literally right, instead of down; still, it's down figuratively.
arrows like digits
All of them take digit arguments, so that e.g. 5j is equivalent to jjjjj.
h and j maintain the guarantee of not exiting the current list, so you can use e.g. 99j to move to the last element, if your list length is smaller than 99.
arrows like regions
When the region is active, the arrows move the mark appropriately with the point. You can activate and deactivate the region by repeatedly pressing m.
You can also mark a symbol with M-m
lispy-mark-symbol). There's no need to be in special for this
command to work. I call these type of bindings global, while the
bindings that only work in special I call local.
arrows like outlines
When located at the outline, j will call
outline-next-visible-heading, and k will call
outline-previous-visible-heading. l will move to the
first list of the outline, while h will jump between the
top-level sexp and the containing outline.
switching to a different side of the expression
Arrows can't do this easily; this can instead be done with
lispy-different). Works for lists and regions.
Moving the code instead of moving around the code
The most basic commands are:
- w is
- s is
These will "hold on" to the current expression while moving it in the appropriate direction. There's no need to worry to mess up with them, since they cancel each other out perfectly.
Note that, just like with the arrows, if you don't have an opening or closing delimiter to "grab", you can mark a symbol M-m to be in special and use w / s.
Modified arrows can move too
o will modify the arrow keys temporarily, just for one command, with a minor mode. You can think of it as making the arrows move the point and the sexp in the usual direction, instead of moving just the point.
- ol: move current sexp outside of the parent list, forwards
- oh: move current sexp outside of the parent list, backwards
- oj: move current sexp inside the next list, making it the first element
- ok: move current sexp inside the preceding list, making it the last element
Extending or shrinking the current list or region
- > (
lispy-slurp) grows the current list or region in the current direction by one sexp
- < (
lispy-barf) shrinks the current list or region in the current direction by one sexp
Similarly to j and k, these commands maintain the guarantee of not exiting the parent list, so you can slurp until the end of the list with e.g. 99>.
This project is very far from being final, I'm expecting to reach
0.99.0 before getting to
1.0.0. The reason is that the package
aims to build intuition to the point of automation. For each small
step in that direction, every small bug is two steps back, since it
breaks the process of building intuition. So every possible situation
needs to be tested and bugs fixed until the package is finally ironed
How can I generate a function call right after the function definition?
I would say to just use 2mcol(:
- mark the function name with 2m
- clone region with c
- move region outside the function body with ol
- wrap the region with parens while deactivating it with (
And this would be a sort of FAQ question / recipe already done there.
Or you could raise an issue like:
Why doesn't F work for Racket?
I would say it's because I haven't implemented it yet, since it was
tricky. But I'll get to it, now that I see that there's some interest
lispy from Racket users.