upiv (use-package insert variable)

The upiv package adds a helper function to insert variables with their current value into use-package forms. The following screencast shows it providing the custom variables for lsp-ui, with their current value (the default), and inserting the :custom form into use-package.

The package supports a basic integration what you would use with the default completion engine, or vertico, where full forms are shown as they would be inserted into the use-package expression.

It also support integration with marginalia, which enhances the listing with a documentation string and nice colors.

Both screencasts show the very basic configuration required for the package, find the Emacs init files in docs. Doom Emacs integration is described in the installation instructions.

Motivation

While tinkering on my configuration I often have to look for variable names to tweak something. I first have to find the variable, which completion systems offer up together with function names, and then have to look at the docs for their value type and current value. This solves this problem for me.

Installation

Manual

Clone the repository and add the package to your load-path.

(add-to-list load-path "path-to-package")
(require 'upiv)

Doom Emacs

In package.el:

(package! upiv :recipe (:host nil :repo "https://forge.arjenwiersma.nl/arjen/upiv"))

In your config.el:

(use-package! upiv
  :config
  (map! (:map emacs-lisp-mode-map
         :localleader
         :desc "Insert custom variable" "c" #'upiv-at-point)))

If you use Doom Emacs, you will have marginalia-mode available, I highly recommend to use the marginalia annotator for variables. To configure the use of marginalia-mode use the following:

(use-package! upiv
  :custom
  ;; enables support for marginalia mode
  (upiv-full-form-in-completion nil)
  :config
  ;; enable marginalia to annotate the upiv-at-point function
  (add-to-list 'marginalia-command-categories '(upiv-at-point . variable))
  (map! (:map emacs-lisp-mode-map
         :localleader
         :desc "Insert custom variable" "c" #'upiv-at-point)))

Development

The screencasts are recorded using asciinema and then converted using gifsicle for compatibility with social networks.

gifsicle basic-upiv.gif --colors 256 -o basic.gif --resize-width 800