custom-buffer-local-keys

custom-buffer-local-keys.el

;; JD Smith 2024, based on https://www.emacswiki.org/emacs/BufferLocalKeys
(defvar-local custom-buffer-local-keys nil
    "Key-bindings to be set up local to the current buffer.
A single (KEY . BINDING) cons or list of such conses, of the form
`bind-keys' accepts.  Set this as a file-local variable to make
bindings local to that buffer only.")

(put 'custom-buffer-local-keys 'safe-local-variable 'consp)

(defvar-local my/custom-buffer-local-map nil)
(defun my/process-custom-buffer-local-keys ()
  "Setup and enable a minor mode if custom-buffer-local-keys is non-nil."
  (when (and (boundp 'custom-buffer-local-keys) custom-buffer-local-keys)
    (let ((map my/custom-buffer-local-map)
	  (keys custom-buffer-local-keys))
      (unless map
	(setq map (make-sparse-keymap))
	(set-keymap-parent map (current-local-map))
	(use-local-map (setq my/custom-buffer-local-map map)))
      (unless (consp (car keys)) (setq keys (list keys)))
      (dolist (k keys) (local-set-key (kbd (car k)) (cdr k))))))

(add-hook 'hack-local-variables-hook #'my/process-custom-buffer-local-keys)

If you'd like to define some keys locally to a single buffer only, this is how to do it. Include the above in your init, then set the file-local variable custom-buffer-local-keys to a cons or list of conses of the form bind-keys would take (which is the same form as the :bind stanza of use-package). These bindings will be automatically enabled locally for that buffer only.

An example, at the end of an org file:

* Local Variables :noexport:
#+begin_src emacs-lisp
Local Variables:
custom-buffer-local-keys: (
("<f9>" . (lambda () (interactive) (my/org-babel-execute) (outline-next-heading)))
("<f8>" . (lambda () (interactive) (my/org-babel-execute) (outline-previous-heading))))
End:
#+end_src

That's a nice way to do it. In the past I put a source block in the file that called local-set-key and then evaluated that block with an eval line in the local variables.

Yeah the key good idea on the wiki was to use a custom buffer-derived minor mode. local-set-key has always seemed poorly named, since the (current-local-map) is usually eq to (mode-map), i.e. the key would be set in all org buffers. I'll probably use this to allocate the same function keys to notional "action, previous, next" commands and have those dtrt in various files. Of course leaving <f10> for activities-resume ;).

In #emacs-channel on irc.libera.chat IRC-network, bpalmer shared these insights:

• a buffer struct literally has a member that is its keymap. The typical behavior of a major mode is (use-local-map the-map-that-the-mode-defined)
• if you want a unique keymap, M-: (use-local-map (make-sparse-keymap)) RET or (what eshell did, iirc) , (use-local-map (copy-keymap eshell-mode-map))
• at that point, local set key will affect the object that is the buffer's keymap.
• The typical usage, remember, is (use-local-map my-mode-map), so mutating that map (like define-key does) will make the changes visible in every mode.
• in every buffer that uses that object.
• But that's just due to mutable objects.
• note another approach is to make a new keymap and use keymap-set-parent to the original mode map, rather than make a copy.
• that way any local-set-key affects only the current buffer, but define-key to the mode map (or local-set-key in a buffer using the mode map) will still affect the current buffer.

Interesting, thanks for sharing that. I came up with a simplified version based on these ideas.