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.
visual-shorthands-refresh	Refresh all overlays visual shorthand.

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

Quicksart: Global Mode

Enable visual-shorthands-mode automatically in all buffers where mappings exist:

(use-package visual-shorthands
  :config
  (global-visual-shorthands-mode 1))

Then you have a few different options for adding shorthand mappings:

Interactive Mapping Creation

The fastest, easiest way to add a visual-shorthands is by calling the command 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.

Note

If global-visual-shorthands-mode is active, the mode enables automatically when you add a mapping to a buffer.

file-local variables

;; At end of your .el file:
;; Local Variables:
;; visual-shorthands-alist: (("visual-shorthands-" . "vs:") ("visual-shorthands--" . "vs--"))
;; End:

per-project in .dir-locals.el

;; In .dir-locals.el at project root
((emacs-lisp-mode . ((visual-shorthands-alist
                      . (("package-long-prefix-" . "plp:")
                         ("package-long-prefix--" . "plp--"))))))

Advanced: manual refresh or auto-refresh on save

For refreshing shorthands on the current buffer, you can use visual-shorthands-refresh, either manually through a binding / M-x or configure it to be execute on certain actions like saving or modifying the buffer.

For refreshing shorthands on buffer save you can do:

buffer-local refresh

Hook is added only in buffers where visual-shorthands-mode is active

(use-package visual-shorthands
  :config
  (global-visual-shorthands-mode 1)

  (add-hook 'visual-shorthands-mode-hook
          (lambda ()
            (when visual-shorthands-mode
              (add-hook 'after-save-hook #'visual-shorthands-refresh nil t)))))

Advanced: automatically apply shorthands while editing

If you want the refresh to happen while editing, not just on save. We can do so by using after-change-functions:

(use-package visual-shorthands
  :config
  (global-visual-shorthands-mode 1)
  (add-hook 'visual-shorthands-mode-hook
            (lambda ()
              (when visual-shorthands-mode
                (add-hook 'after-change-functions
                          (lambda (&rest _) (visual-shorthands-refresh))
                          nil t)))))

Warning

Refreshing on every modification is expensive for large buffers. Consider refreshing manually through visual-shorthands-refresh.

Customization

See M-x customize-group RET visual-shorthands RET for all options.

Key customization variables:

visual-shorthands-trigger

Control when symbols are revealed

• 'always (default): Reveal when cursor enters symbol
• 'on-change: Reveal only when buffer is modified

visual-shorthands-delay

Delay in seconds before revealing (default: 0.0)

visual-shorthands-face

Face for shorthand display