1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
|
#+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="http://elpa.gnu.org/packages/cape.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/cape.svg"/></a>
#+html: <a href="http://elpa.gnu.org/devel/cape.html"><img alt="GNU-devel ELPA" src="https://elpa.gnu.org/devel/cape.svg"/></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>
* 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]].
#+html: <img src="https://github.com/minad/cape/blob/logo/cape.png?raw=true" align="right" width="30%">
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 file
+ ~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.
#+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)
("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)
)
#+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
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~.
#+begin_src emacs-lisp
(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)))))
#+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 and should only be used in special scenarios.
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~.
#+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
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.
#+begin_src emacs-lisp
(setq-local completion-at-point-functions
(list (cape-capf-buster #'some-caching-capf)))
#+end_src
** completing-read adapter
/Wrap your completion command in a Cape and turn it into a Capf!/
Sometimes it is useful to reuse existing completion commands, which call
~completing-read~ to generate candidates for completion at point. One such example
is the command ~consult-history~.
#+begin_src emacs-lisp
(defalias 'eshell-buffer-name-capf (cape-interactive-capf (cape-completing-read-to-capf #'consult-history)))
#+end_src
** 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.
* Contributions
Since this package is part of [[http://elpa.gnu.org/packages/marginalia.html][GNU ELPA]] contributions require a copyright
assignment to the FSF.
|
