Repository navigation
donkey 1.15.0 — a delimiter closes itself as you type, if you ask it to
A feature release, and the feature is opt-in: nothing about your typing
changes until you turn it on.
DONKEY can close a delimiter while you type. Type { and you get {}
with the cursor between the halves; type the closing half where one
already stands and the cursor steps over it rather than doubling it.
It is off by default and stays off, because INSERT state is otherwise
entirely Emacs's — C-g is the only key DONKEY holds there — and a
package that changed how you type on upgrade would be taking a liberty.
The delimiters come from donkey-mark-pair-delimiters, the same table
m i selects from and the wrap keys use. A pair you add there is one
you can type as well as select and wrap, with no second list to keep in
step.
Added
donkey-pair-mode— a global minor mode, off by default. With it
on, an opening delimiter writes its closing half and leaves the
cursor between the two. The closing half, typed where that character
already stands, steps over it.DELbetween the halves of an empty
pair takes both, andDELanywhere else is still your major mode's.
A count types and pairs nothing, soC-u 3 (gives you three
brackets.donkey-pair-delimiters— how much of the table is used.safe,
the default, is the brackets and the quotes: eight of them.allis
every pair in the table: twenty-one. A list is exactly those
characters.nilleaves the mode on with nothing pairing.donkey-pair-safe-exclusions— whatsafeholds back. Thirteen
characters that are ordinary text far more often than they are
delimiters: the apostrophe in "don't", the colon in prose, the
less-than sign. Add to it when a pair you put in the table is one you
never want to type.donkey-pair-delimiter-exceptions— drop one delimiter in one
major mode. Ships with the quote, the backquote and the hash held
back in Lisp buffers, where#'is a function quote.donkey-pair-delimiter-inclusions— the opposite, and HTML is
what it is for. The less-than sign is punctuation in prose, which is
whysafeleaves it out, but almost every line of an HTML buffer
sits between one and its closer. One row namingsgml-modecovers
html-modeandmhtml-modeas well.donkey-pair-excluded-modes— turn the pairing off by major mode
while NORMAL state stays on.donkey-pair-stand-down— on by default, and it means DONKEY
does nothing wheresmartparens-modeis on. Set it to nil to pair
regardless.M-x donkey-pair-refresh— hand the delimiters to Emacs again
after a plainsetq.setoptneeds no help.
Where electric-pair-mode is on, Emacs keeps the job and DONKEY hands
it the delimiters instead of pairing anything itself, so a pair Emacs
had no way to know about — (?# . ?#) say — is one it pairs now.
M-x donkey-debug-platform names whoever has the job in the buffer you
ran it from, and how many delimiters pair there.
Fixed — you will notice these
C-h f— six commands showed a key reference as brackets round a
symbol, "press[donkey-refresh-wrap-keys]", rather than the key
itself. Four of the six are in the wrapping code and have read that
way since wrapping shipped. A lone backslash before the bracket is
dropped by the Lisp reader as an unknown escape, and neither the byte
compiler nor checkdoc reports it.
Under the hood
- Every option the typing hook reads is coerced where it is used rather
than trusted. A signal raised frompost-self-insert-hooktakes the
hook off for the session, so one mis-typed character in an init file
would have turned the pairing off silently and for good. A value of
the wrong shape is skipped now and your typing continues. - The delimiter prompt reads the pair table after the prompt rather
than before it, so a pair added while it waits is one it accepts. - The pairing hook runs ahead of the pairing packages and at most once
per press, because a package that writes its own closing half runs
the whole hook again with a character nobody typed. - The README's tables of what pairs where are read out of the file by
the test suite and checked against the running Emacs, so a table that
drifts from the code fails the build rather than misleading a reader.
Upgrading
Nothing to do. The mode is off until you turn it on:
(donkey-pair-mode 1)If you already use electric-pair-mode or Smartparens, turning it on
is still safe: DONKEY works out who should do the job and gets out of
the way. M-x donkey-debug-platform says who has it.