Skip to content

Document how CIDER picks the form a command acts on - #4174

Merged
bbatsov merged 1 commit into
masterfrom
docs-form-selection
Aug 28, 2026
Merged

Document how CIDER picks the form a command acts on#4174
bbatsov merged 1 commit into
masterfrom
docs-form-selection

Conversation

@bbatsov

@bbatsov bbatsov commented Aug 28, 2026

Copy link
Copy Markdown
Member

Stacked on #4173, so the diff to review here is just the two doc pages.

The terminology section named last-sexp and sexp-at-point but never said what follows from them, so the rules had to be inferred command by command. There's now a section that spells out the three ways to say which form you mean, a table of the at-point variants, and a snippet you can paste to rebind the flagship keys to them if you prefer pointing at a form over standing after it.

It also records why the cursor goes after the form rather than on it, which until now was folklore: that's how Emacs Lisp's own eval-last-sexp works, and SLIME's and SLY's, and following that prior art has been a deliberate choice rather than an accident. The keybindings section already says as much about keys; the same reasoning governs form selection, and after the recent round-trip on this it seemed worth writing down.

Macroexpansion gets its own section, since it's the one operation that resolves its target differently: an expansion needs a call form, so a bare symbol widens to the call around it and an opening delimiter expands the form it opens rather than the parent.

Two things I have not done here. There are no GIFs illustrating the selection modes yet - they want a live REPL to show real evaluation overlays, and that harness is worth building properly rather than faking the illustration; I'd like to do it as its own PR. And I'd like to look at what SLIME, SLY, Geiser and the Emacs Lisp modes do that we don't, since we've only ever borrowed the convention itself and there may be more worth taking.

@bbatsov
bbatsov force-pushed the at-point-variants branch from 55d90c8 to d5001f1 Compare August 28, 2026 09:08
@bbatsov
bbatsov force-pushed the docs-form-selection branch from c86614b to 776a50f Compare August 28, 2026 09:08
@bbatsov
bbatsov force-pushed the at-point-variants branch from d5001f1 to 1e73566 Compare August 28, 2026 10:46
@bbatsov
bbatsov changed the base branch from at-point-variants to master August 28, 2026 12:03
The terminology section named last-sexp and sexp-at-point but never said
what follows from them, so the rules had to be inferred command by
command. There's now a section spelling out the three ways to say which
form you mean, a table of the at-point variants, and a copy-pasteable
snippet for rebinding the flagship keys to them.

It also records why the cursor goes after the form rather than on it:
that's Emacs Lisp's own eval-last-sexp, and SLIME's and SLY's, and
following that prior art has been a deliberate choice rather than an
accident. The keybindings section already said as much about keys; the
same reasoning governs form selection.

Macroexpansion gets its own section, since it is the one operation that
resolves its target differently: an expansion needs a call form, so a
bare symbol widens to the call around it.
@bbatsov
bbatsov force-pushed the docs-form-selection branch from 776a50f to ee2fc2d Compare August 28, 2026 12:04
@bbatsov
bbatsov merged commit 1971e4f into master Aug 28, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant