Skip to content

donkey 1.15.0 — a delimiter closes itself as you type, if you ask it to

Choose a tag to compare

@YardQuit YardQuit released this 21 Sep 16:39
· 155 commits to master since this release
9f172d4

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. DEL between the halves of an empty
    pair takes both, and DEL anywhere else is still your major mode's.
    A count types and pairs nothing, so C-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. all is
    every pair in the table: twenty-one. A list is exactly those
    characters. nil leaves the mode on with nothing pairing.
  • donkey-pair-safe-exclusions — what safe holds 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
    why safe leaves it out, but almost every line of an HTML buffer
    sits between one and its closer. One row naming sgml-mode covers
    html-mode and mhtml-mode as 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 where smartparens-mode is on. Set it to nil to pair
    regardless.
  • M-x donkey-pair-refresh — hand the delimiters to Emacs again
    after a plain setq. setopt needs 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 from post-self-insert-hook takes 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.