Introducing completions overlays

I’ve been working on package for emacs called completions-overlay that allows you to place custom overlays on arbitrary completion candidates. This is some extra visual sugar on top of the default emacs completion framework which has gotten a major overhaul in previous versions¹. Below is a quick demonstration of a custom overlay that gives the status and major mode of the buffer candidate when you run the command switch-to-buffer:

Here’s another which provides the docstring of a function as an overlay in the completions buffer, saving you opening another *Help* buffer:

The package is fairly simple and allows you to define how overlays are defined for any completing read function. Below I give my own configuration of the package:

(add-to-list 'load-path "~/git/completions-overlay")
(require 'completions-overlay)

(setq completions-overlay-supported-functions  `((switch-to-buffer . namilus-buffer-annotation)
                                                 (describe-function . namilus-function-annotation)))

(defun namilus-buffer-annotation (buffer-name)
  (let ((buf (get-buffer buffer-name)))
    (format "%s  %s" (format-mode-line "%1*%1+%1@ %m" nil nil buf) buffer-name)))

(defun namilus-function-annotation (fun)
  (if-let ((doc (documentation (intern fun))))
      (string-replace "\n" " " doc)
    "Function not documented"))

(define-key minibuffer-mode-map (kbd "C-;") #'completions-overlay-toggle)
(completions-overlay-mode)

The key variable here is completions-overlay-supported-functions, which is an alist whose elements are of the form (func . handler), where func is the completing read function whose candidates you’d like to place overlays on top of, and handler is a function that takes as argument the string of the completion candidate as it appears in the completions buffer, and returns a string for it’s overlay. I’ve also set the keybinding C-; to toggle the overlay on and off.

This is a very generic package and I can imagine a lot of custom workflows can be built on top. I currently use it as shown above, to quickly see a docstring when searching through functions and to see buffer status right in the completions buffer. The excellent package marginalia does this too but provides information for all the candidates at once in the margins which can sometimes lead to a cluttered completions buffer. This package provides an alternative way of showing this information that suit better depending on the scenario or your preferences.

This package is currently hosted only on github and is actively in development, however all the main functionality is currently implemented. Additionally, only the default emacs completions framework is supported, however I’d like to change that soon, depending on how tough that is and demand for the functionality.