#+title: cape.el - Let your completions fly!
#+author: Daniel Mendler
#+language: en
#+export_file_name: cape.texi
#+texinfo_dir_category: Emacs
#+texinfo_dir_title: Cape: (cape).
#+texinfo_dir_desc: Completion At Point Extensions

#+html: <a href="https://www.gnu.org/software/emacs/"><img alt="GNU Emacs" src="https://github.com/minad/corfu/blob/screenshots/emacs.svg?raw=true"/></a>
#+html: <a href="https://melpa.org/#/cape"><img alt="MELPA" src="https://melpa.org/packages/cape-badge.svg"/></a>
#+html: <a href="https://stable.melpa.org/#/cape"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/cape-badge.svg"/></a>
#+html: <img src="https://upload.wikimedia.org/wikipedia/en/3/35/Supermanflying.png" align="right">

* Introduction

Cape provides a bunch of Completion At Point Extensions which can be used in
combination with my [[https://github.com/minad/corfu][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 [[https://github.com/company-mode/company-mode][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 anywere.

On the more experimental side, Cape has the super power to transform Company
backends into Capfs and merge multiple Capfs into a Super-Capf!

* Configuration

Cape is available from MELPA. In the long term some of the Capfs provided by
this package should be upstreamed into Emacs itself.

#+begin_src emacs-lisp
  ;; 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))
    :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-dabbrev)
    (add-to-list 'completion-at-point-functions #'cape-keyword)
    ;;(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)
  )
#+end_src

* 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:

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

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.

#+begin_src emacs-lisp
  (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))
#+end_src

** 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. 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~.

#+begin_src emacs-lisp
  ;; 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)))
#+end_src

** 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.

#+begin_src emacs-lisp
  (setq-local completion-at-point-functions
              (list (cape-capf-buster #'some-caching-capf)))
#+end_src

** Other Capf transformers

- ~cape-silent-capf~: Wrap a chatty Capf and silence it.
- ~cape-noninterruptible-capf~: Protect a Capf which does not like to be interrupted.
- ~cape-interactive-capf~: Create a Capf which can be called interactively.
- ~cape-capf-with-properties~: Add completion properties to a Capf.
- ~cape-capf-with-predicate~: Add candidate predicate to a Capf.
- ~cape-capf-with-case-fold~: Create a Capf which is case insensitive.