cape.el - Let your completions fly!

Introduction

Cape provides a bunch of Completion At Point Extensions which can be used in combination with my Corfu completion UI or the default completion UI. The completion backends used by completion-at-point are so called completion-at-point-functions (Capfs). In principle, the Capfs provided by Cape can also be used by Company.

You can register the cape-* functions in the completion-at-point-functions list. This makes the backends available for completion, which is usually invoked by pressing TAB or M-TAB. The functions can also be invoked interactively to trigger the respective completion at point. You can bind them directly to a key in your user configuration. Notable commands/capfs are cape-line for completion of a line from the current buffer and cape-file for completion of a file name. The command cape-symbol is particularily useful for documentation of Elisp packages or configurations, since it completes elisp symbols anywhere.

On the more experimental side, Cape has the super power to transform Company backends into Capfs and merge multiple Capfs into a Super-Capf! These transformers allow you to still take advantage of Company backends even if you are not using Company as frontend.

Available Capfs

cape-dabbrev: Complete word from current buffers
cape-file: Complete file name
cape-keyword: Complete programming language keyword
cape-symbol: Complete Elisp symbol
cape-abbrev: Complete abbreviation (add-global-abbrev, add-mode-abbrev)
cape-ispell: Complete word from Ispell dictionary
cape-dict: Complete word from dictionary file
cape-line: Complete entire line from current buffer
cape-tex: Complete unicode char from TeX command, e.g. \hbar.
cape-sgml: Complete unicode char from Sgml entity, e.g., &alpha.
cape-rfc1345: Complete unicode char using RFC 1345 mnemonics.

Configuration

Cape is available on GNU ELPA and MELPA. You can install the package with package-install. In the long term some of the Capfs provided by this package could be upstreamed into Emacs itself.

;; Enable Corfu completion UI
;; See the Corfu README for more configuration tips.
(use-package corfu
  :init
  (corfu-global-mode))

;; Add extensions
(use-package cape
  ;; Bind dedicated completion commands
  :bind (("C-c p p" . completion-at-point) ;; capf
         ("C-c p t" . complete-tag)        ;; etags
         ("C-c p d" . cape-dabbrev)        ;; or dabbrev-completion
         ("C-c p f" . cape-file)
         ("C-c p k" . cape-keyword)
         ("C-c p s" . cape-symbol)
         ("C-c p a" . cape-abbrev)
         ("C-c p i" . cape-ispell)
         ("C-c p l" . cape-line)
         ("C-c p w" . cape-dict)
         ("C-c p \\" . cape-tex)
         ("C-c p _" . cape-tex)
         ("C-c p ^" . cape-tex)
         ("C-c p &" . cape-sgml)
         ("C-c p r" . cape-rfc1345))
  :init
  ;; Add `completion-at-point-functions', used by `completion-at-point'.
  (add-to-list 'completion-at-point-functions #'cape-file)
  (add-to-list 'completion-at-point-functions #'cape-tex)
  (add-to-list 'completion-at-point-functions #'cape-dabbrev)
  (add-to-list 'completion-at-point-functions #'cape-keyword)
  ;;(add-to-list 'completion-at-point-functions #'cape-sgml)
  ;;(add-to-list 'completion-at-point-functions #'cape-rfc1345)
  ;;(add-to-list 'completion-at-point-functions #'cape-abbrev)
  ;;(add-to-list 'completion-at-point-functions #'cape-ispell)
  ;;(add-to-list 'completion-at-point-functions #'cape-dict)
  ;;(add-to-list 'completion-at-point-functions #'cape-symbol)
  ;;(add-to-list 'completion-at-point-functions #'cape-line)
)

Experimental features

Company adapter

Wrap your Company backend in a Cape and turn it into a Capf!

Cape provides an adapter for Company backends cape-company-to-capf. The adapter transforms Company backends to Capfs which are understood by the built-in Emacs completion mechanism. The function is approximately the inverse of the company-capf backend from Company. The adapter is still experimental and may have certain edge cases. The adapter can be used as follows:

;; Use Company backends as Capfs.
(setq-local completion-at-point-functions
  (mapcar #'cape-company-to-capf
    (list #'company-files #'company-ispell #'company-dabbrev)))

Note that the adapter does not require Company to be installed. Backends implementing the Company specification do not necessarily have to depend on Company, however in practice most backends do. The following shows a small example completion backend, which can be used with both completion-at-point (Corfu, default completion) and Company.

(defvar emojis
  '((":-D" . "😀")
    (";-)" . "😉")
    (":-/" . "😕")
    (":-(" . "🙁")
    (":-*" . "😙")))

(defun emoji-backend (action &optional arg &rest _)
  (pcase action
    ('prefix (and (memq (char-before) '(?: ?\;))
                  (cons (string (char-before)) t)))
    ('candidates (all-completions arg emojis))
    ('annotation (concat " " (cdr (assoc arg emojis))))
    ('post-completion
     (let ((str (buffer-substring (- (point) 3) (point))))
       (delete-region (- (point) 3) (point))
     (insert (cdr (assoc str emojis)))))))

;; Register emoji backend with `completion-at-point'
(setq completion-at-point-functions
      (list (cape-company-to-capf #'emoji-backend)))

;; Register emoji backend with Company.
(setq company-backends '(emoji-backend))

It is possible to merge/group multiple Company backends and use them as a single Capf using the company--multi-backend-adapter function from Company. The adapter transforms multiple Company backends into a single Company backend, which can then be used as a Capf via cape-company-to-capf.

(require 'company)
;; Use the company-dabbrev and company-elisp backends together.
(setq completion-at-point-functions
      (list
       (cape-company-to-capf
        (apply-partially #'company--multi-backend-adapter
                         '(company-dabbrev company-elisp)))))

Super-Capf - Merging multiple Capfs

Throw multiple Capfs under the Cape and get a Super-Capf!

Cape supports merging multiple Capfs using the function cape-super-capf. This feature is experimental and should only be used in special scenarios. Don’t use cape-super-capf if you are not 100% sure that you need it!

Note that cape-super-capf is not needed if you want to use multiple Capfs which are tried one by one, e.g., it is perfectly possible to use cape-file together with the lsp-mode Capf or other programming mode Capfs by adding cape-file to the completion-at-point-functions list. The file completion will be available in comments and string literals. cape-super-capf is only needed if you want to combine multiple Capfs, such that the candidates from multiple sources appear together in the completion list at the same time.

Completion table merging works only for tables which are sufficiently well-behaved and tables which do not define completion boundaries. cape-super-capf has the same restrictions as completion-table-merge and completion-table-in-turn. As a simple rule of thumb, cape-super-capf works only well for static completion functions like cape-dabbrev, cape-keyword, cape-ispell, etc., but not for complex multi-step completions like cape-file.

;; Merge the dabbrev, dict and keyword capfs, display candidates together.
(setq-local completion-at-point-functions
            (list (cape-super-capf #'cape-dabbrev #'cape-dict #'cape-keyword)))

See also the aforementioned company--multi-backend-adapter from Company, which allows you to merge multiple Company backends.

Capf-Buster - Cache busting

The Capf-Buster ensures that you always get a fresh set of candidates!

If a Capf caches the candidates for too long we can use a cache busting Capf-transformer. For example the Capf merging function cape-super-capf creates a Capf, which caches the candidates for the whole lifetime of the Capf. Therefore you may want to combine a merged Capf with a cache buster under some circumstances. It is noteworthy that the company-capf backend from Company refreshes the completion table frequently. With the cape-capf-buster we can achieve a similarly refreshing strategy.

(setq-local completion-at-point-functions
            (list (cape-capf-buster #'some-caching-capf)))

Other Capf transformers

cape-interactive-capf: Create a Capf which can be called interactively.
cape-wrap-silent, cape-capf-silent: Wrap a chatty Capf and silence it.
cape-wrap-purify, cape-capf-purify: Purify a broken Capf and ensure that it does not modify the buffer.
cape-wrap-noninterruptible, cape-capf-noninterruptible: Protect a Capf which does not like to be interrupted.
cape-wrap-case-fold, cape-capf-case-fold: Create a Capf which is case insensitive.
cape-wrap-properties, cape-capf-properties: Add completion properties to a Capf.
cape-wrap-predicate, cape-capf-predicate: Add candidate predicate to a Capf.
cape-wrap-prefix-length, cape-capf-prefix-length: Enforce a minimal prefix length.

Contributions

Since this package is part of GNU ELPA contributions require a copyright assignment to the FSF.

ilohmar/cape