visual-shorthands - Purely visual prefix abbreviations

Visual-shorthands provides display-only abbreviations for long symbol prefixes using overlays. Unlike Emacs’ built-in read-symbol-shorthands, which requires file-local variables and affects eval, visual-shorthands operates purely at the display layer and can be toggled interactively.

The package is designed for reading code written by others with verbose naming conventions, such as Emacs Lisp code and packages, but it can still be used in other languages. If you need actual Namespaces, use the built-in shorthands. Symbols are automatically revealed when the cursor enters them, allowing normal navigation and editing of the actual buffer text.

Screenshots

Tip

Also using lisp-docstring-toggle to hide docstrings in the buffer for readability’s sake.

Commands

Note

Mappings are buffer-local.

visual-shorthands-mode	Toggle visual shorthand overlays with auto-reveal in current buffer.
visual-shorthands-add-mapping	Add visual shorthand mapping from LONGHAND to SHORTHAND.
visual-shorthands-clear-mappings	Clear all visual shorthand mappings.
visual-shorthands-remove-mapping	Remove visual shorthand mapping for LONGHAND.

Installation

visual-shorthands is on MELPA, so you can run M-x package-install ⏎ visual-shorthands in Emacs.

Manual

Clone or download this repository and run M-x package-install-file ⏎ on the repository directory.

Or from use-package (Emacs 30+):

(use-package visual-shorthands
  :vc ( :url "https://github.com/gggion/visual-shorthands.el"
             :rev :newest)
  :hook (emacs-lisp-mode . visual-shorthands-mode))

Straight or Elpaca

(straight-use-package 'visual-shorthands) 
;; OR
(elpaca visual-shorthands)

Or from use-package:

(use-package visual-shorthands
  :straight t  ; use :ensure t for Elpaca
  :hook (emacs-lisp-mode . visual-shorthands-mode))

Configuration

Setup

(use-package visual-shorthands
  :config
  ;; Enable in specific modes
  (add-hook 'emacs-lisp-mode-hook #'visual-shorthands-mode))

Interactive Mapping Creation

As shown in the above gif, call M-x visual-shorthands-add-mapping to create mappings interactively. As you type the longhand prefix, matching symbols in the buffer are highlighted with visual-shorthands-preview-face, needs the mode to be active in the buffer.

Project-Specific Configuration

You can also use directory-local variables for project-specific mappings.

;; In .dir-locals.el at project root
((nil . ((eval . (progn
                   (visual-shorthands-add-mapping "package-function-long-prefix--" "pflp:")
                   (visual-shorthands-mode 1))))))