corfu.info (30860B)
1 This is docYXxwrO.info, produced by makeinfo version 6.7 from 2 corfu.texi. 3 4 INFO-DIR-SECTION Emacs misc features 5 START-INFO-DIR-ENTRY 6 * Corfu: (corfu). Completion Overlay Region FUnction. 7 END-INFO-DIR-ENTRY 8 9 10 File: docYXxwrO.info, Node: Top, Next: Features, Up: (dir) 11 12 corfu.el - Completion Overlay Region FUnction 13 ********************************************* 14 15 Corfu enhances completion at point with a small completion popup. The 16 current candidates are shown in a popup below or above the point. Corfu 17 is the minimalistic ‘completion-in-region’ counterpart of the Vertico 18 (https://github.com/minad/vertico) minibuffer UI. 19 20 Corfu is a small package, which relies on the Emacs completion 21 facilities and concentrates on providing a polished completion UI. 22 Completions are either provided by commands like ‘dabbrev-completion’ or 23 by pluggable backends (‘completion-at-point-functions’, Capfs). Most 24 programming language major modes implement a Capf. Furthermore the 25 language server packages, Eglot and Lsp-mode, use Capfs which talk to 26 the LSP server to retrieve the completions. Corfu does not include its 27 own completion backends. The Emacs built-in Capfs and the Capfs 28 provided by other programming language packages are usually sufficient. 29 A few additional Capfs and completion utilities are provided by the Cape 30 (https://github.com/minad/cape) package. 31 32 *NOTE*: Corfu uses child frames to show the popup and falls back to 33 the default setting of the ‘completion-in-region-function’ on 34 non-graphical displays. If you want to use Corfu in the terminal, 35 install the package corfu-terminal 36 (https://codeberg.org/akib/emacs-corfu-terminal), which provides an 37 alternative overlay-based display. 38 39 * Menu: 40 41 * Features:: 42 * Installation and Configuration:: 43 * Key bindings:: 44 * Extensions:: 45 * Complementary packages:: 46 * Alternatives:: 47 * Contributions:: 48 49 — The Detailed Node Listing — 50 51 Installation and Configuration 52 53 * Auto completion:: 54 * Completing in the minibuffer:: 55 * Completing in the Eshell or Shell:: 56 * Orderless completion:: 57 * TAB-and-Go completion:: 58 * Transfer completion to the minibuffer:: 59 60 61 62 File: docYXxwrO.info, Node: Features, Next: Installation and Configuration, Prev: Top, Up: Top 63 64 1 Features 65 ********** 66 67 • Timer-based auto-completions (_off_ by default, set ‘corfu-auto’). 68 • Popup display with scrollbar indicator and arrow key navigation. 69 • The popup can be summoned explicitly by pressing ‘TAB’ at any time. 70 • The current candidate is inserted with ‘TAB’ and selected with 71 ‘RET’. 72 • Candidates sorting by prefix, string length and alphabetically. 73 • The selected candidate is previewed (configurable via 74 ‘corfu-preview-current’). 75 • The selected candidate automatically committed on further input by 76 default. (configurable via ‘corfu-preview-current’). 77 • The Orderless (https://github.com/oantolin/orderless) completion 78 style is supported. The filter string can contain arbitrary 79 characters, after inserting a space via ‘M-SPC’ (configurable via 80 ‘corfu-quit-at-boundary’ and ‘corfu-separator’). 81 • Deferred completion style highlighting for performance. 82 • Support for candidate annotations (‘annotation-function’, 83 ‘affixation-function’). 84 • Deprecated candidates are crossed out in the display. 85 • Icons can be provided by an external package via margin formatter 86 functions. 87 • Rich set of extensions: Quick keys, Index keys, Sorting by history, 88 Candidate documentation in echo area, popup or separate buffer 89 90 91 File: docYXxwrO.info, Node: Installation and Configuration, Next: Key bindings, Prev: Features, Up: Top 92 93 2 Installation and Configuration 94 ******************************** 95 96 Corfu is available from GNU ELPA 97 (https://elpa.gnu.org/packages/corfu.html), such that it can be 98 installed directly via ‘package-install’. After installation, the 99 global minor mode can be enabled with ‘M-x global-corfu-mode’. In order 100 to configure Corfu and other packages in your init.el, you may want to 101 use ‘use-package’. 102 103 Corfu is highly flexible and customizable via ‘corfu-*’ customization 104 variables, such that you can adapt it precisely to your requirements. 105 However in order to quickly try out the Corfu completion package, it 106 should be sufficient to activate ‘global-corfu-mode’. You can 107 experiment with manual completion for example in an Elisp buffer or in 108 an Eshell or Shell buffer. For auto completion, set ‘corfu-auto=t’ 109 before turning on ‘global-corfu-mode’. 110 111 Here is an example configuration: 112 113 (use-package corfu 114 ;; Optional customizations 115 ;; :custom 116 ;; (corfu-cycle t) ;; Enable cycling for `corfu-next/previous' 117 ;; (corfu-auto t) ;; Enable auto completion 118 ;; (corfu-separator ?\s) ;; Orderless field separator 119 ;; (corfu-quit-at-boundary nil) ;; Never quit at completion boundary 120 ;; (corfu-quit-no-match nil) ;; Never quit, even if there is no match 121 ;; (corfu-preview-current nil) ;; Disable current candidate preview 122 ;; (corfu-preselect-first nil) ;; Disable candidate preselection 123 ;; (corfu-on-exact-match nil) ;; Configure handling of exact matches 124 ;; (corfu-scroll-margin 5) ;; Use scroll margin 125 126 ;; Enable Corfu only for certain modes. 127 ;; :hook ((prog-mode . corfu-mode) 128 ;; (shell-mode . corfu-mode) 129 ;; (eshell-mode . corfu-mode)) 130 131 ;; Recommended: Enable Corfu globally. 132 ;; This is recommended since Dabbrev can be used globally (M-/). 133 ;; See also `corfu-excluded-modes'. 134 :init 135 (global-corfu-mode)) 136 137 ;; A few more useful configurations... 138 (use-package emacs 139 :init 140 ;; TAB cycle if there are only few candidates 141 (setq completion-cycle-threshold 3) 142 143 ;; Emacs 28: Hide commands in M-x which do not apply to the current mode. 144 ;; Corfu commands are hidden, since they are not supposed to be used via M-x. 145 ;; (setq read-extended-command-predicate 146 ;; #'command-completion-default-include-p) 147 148 ;; Enable indentation+completion using the TAB key. 149 ;; `completion-at-point' is often bound to M-TAB. 150 (setq tab-always-indent 'complete)) 151 152 Dabbrev completion is based on ‘completion-in-region’ and can be used 153 with Corfu. You may want to swap the ‘dabbrev-completion’ with the 154 ‘dabbrev-expand’ key for easier access, if you prefer completion. Also 155 take a look at the ‘cape-dabbrev’ completion at point function provided 156 by my Cape (https://github.com/minad/cape) package. 157 158 ;; Use Dabbrev with Corfu! 159 (use-package dabbrev 160 ;; Swap M-/ and C-M-/ 161 :bind (("M-/" . dabbrev-completion) 162 ("C-M-/" . dabbrev-expand)) 163 ;; Other useful Dabbrev configurations. 164 :custom 165 (dabbrev-ignored-buffer-regexps '("\\.\\(?:pdf\\|jpe?g\\|png\\)\\'"))) 166 167 If you start to configure the package more deeply, I recommend to 168 give the Orderless completion style a try for filtering. Orderless 169 completion is different from the familiar prefix TAB completion. Corfu 170 can be used with the default completion styles. The use of Orderless is 171 not a necessity. 172 173 ;; Optionally use the `orderless' completion style. 174 (use-package orderless 175 :init 176 ;; Configure a custom style dispatcher (see the Consult wiki) 177 ;; (setq orderless-style-dispatchers '(+orderless-dispatch) 178 ;; orderless-component-separator #'orderless-escapable-split-on-space) 179 (setq completion-styles '(orderless basic) 180 completion-category-defaults nil 181 completion-category-overrides '((file (styles . (partial-completion)))))) 182 183 The ‘basic’ completion style is specified as fallback in addition to 184 ‘orderless’ in order to ensure that completion commands which rely on 185 dynamic completion tables, e.g., ‘completion-table-dynamic’ or 186 ‘completion-table-in-turn’, work correctly. See ‘+orderless-dispatch’ 187 in the Consult wiki (https://github.com/minad/consult/wiki) for an 188 advanced Orderless style dispatcher. Additionally enable 189 ‘partial-completion’ for file path expansion. ‘partial-completion’ is 190 important for file wildcard support. Multiple files can be opened at 191 once with ‘find-file’ if you enter a wildcard. You may also give the 192 ‘initials’ completion style a try. 193 194 See also the Corfu Wiki (https://github.com/minad/corfu/wiki) and the 195 Cape manual (https://github.com/minad/cape) for additional Capf 196 configuration tips. The Eglot and Lsp-mode configurations are 197 documented in the wiki. For more general documentation read the chapter 198 about completion in the Emacs manual 199 (https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html). 200 If you want to create your own Capfs, you can find documentation about 201 completion in the Elisp manual 202 (https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html). 203 204 * Menu: 205 206 * Auto completion:: 207 * Completing in the minibuffer:: 208 * Completing in the Eshell or Shell:: 209 * Orderless completion:: 210 * TAB-and-Go completion:: 211 * Transfer completion to the minibuffer:: 212 213 214 File: docYXxwrO.info, Node: Auto completion, Next: Completing in the minibuffer, Up: Installation and Configuration 215 216 2.1 Auto completion 217 =================== 218 219 Auto completion is disabled by default, but can be enabled by setting 220 ‘corfu-auto=t’. Furthermore you may want to configure Corfu to quit 221 completion eagerly, such that the completion popup stays out of your way 222 when it appeared unexpectedly. 223 224 ;; Enable auto completion and configure quitting 225 (setq corfu-auto t 226 corfu-quit-no-match 'separator) ;; or t 227 228 I recommend to experiment a bit with the various settings and key 229 bindings to find a configuration which works for you. There is no one 230 size fits all solution. Some people like auto completion, some like 231 manual completion, some want to cycle with TAB and some with the arrow 232 keys. 233 234 In case you like aggressive auto completion settings, where the 235 completion popup appears immediately, I recommend to use a cheap 236 completion style like ‘basic’, which performs prefix filtering. In this 237 case Corfu completion should still be very fast in buffers with 238 efficient completion backends. You can try the following settings in an 239 Elisp buffer or the Emacs scratch buffer. 240 241 ;; Aggressive completion, cheap prefix filtering. 242 (setq-local corfu-auto t 243 corfu-auto-delay 0 244 corfu-auto-prefix 0 245 completion-styles '(basic)) 246 247 If you want to combine fast prefix filtering and Orderless filtering 248 you can still do that by defining a custom Orderless completion style 249 via ‘orderless-define-completion-style’. We use a custom style 250 dispatcher, which enables prefix filtering for input shorter than 4 251 characters. Note that such a setup is quite advanced. Please refer to 252 the Orderless documentation and source code for further details. 253 254 (defun orderless-fast-dispatch (word index total) 255 (and (= index 0) (= total 1) (length< word 4) 256 `(orderless-regexp . ,(concat "^" (regexp-quote word))))) 257 258 (orderless-define-completion-style orderless-fast 259 (orderless-style-dispatchers '(orderless-fast-dispatch)) 260 (orderless-matching-styles '(orderless-literal orderless-regexp))) 261 262 (setq-local corfu-auto t 263 corfu-auto-delay 0 264 corfu-auto-prefix 0 265 completion-styles '(orderless-fast)) 266 267 268 File: docYXxwrO.info, Node: Completing in the minibuffer, Next: Completing in the Eshell or Shell, Prev: Auto completion, Up: Installation and Configuration 269 270 2.2 Completing in the minibuffer 271 ================================ 272 273 Corfu can be used for completion in the minibuffer, since it relies on 274 child frames to display the candidates. By default, ‘global-corfu-mode’ 275 does not activate ‘corfu-mode’ in the minibuffer, to avoid interference 276 with specialised minibuffer completion UIs like Vertico or Mct. However 277 you may still want to enable Corfu completion for commands like ‘M-:’ 278 (‘eval-expression’) or ‘M-!’ (‘shell-command’), which read from the 279 minibuffer. Activate ‘corfu-mode’ only if ‘completion-at-point’ is 280 bound in the minibuffer-local keymap to achieve this effect. 281 282 (defun corfu-enable-in-minibuffer () 283 "Enable Corfu in the minibuffer if `completion-at-point' is bound." 284 (when (where-is-internal #'completion-at-point (list (current-local-map))) 285 ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion 286 (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup 287 corfu-popupinfo-delay nil) 288 (corfu-mode 1))) 289 (add-hook 'minibuffer-setup-hook #'corfu-enable-in-minibuffer) 290 291 You can also enable Corfu more generally for every minibuffer, as 292 long as no other completion UI is active. If you use Mct or Vertico as 293 your main minibuffer completion UI, the following snippet should yield 294 the desired result. 295 296 (defun corfu-enable-always-in-minibuffer () 297 "Enable Corfu in the minibuffer if Vertico/Mct are not active." 298 (unless (or (bound-and-true-p mct--active) 299 (bound-and-true-p vertico--input)) 300 ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion 301 (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup 302 corfu-popupinfo-delay nil) 303 (corfu-mode 1))) 304 (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1) 305 306 307 File: docYXxwrO.info, Node: Completing in the Eshell or Shell, Next: Orderless completion, Prev: Completing in the minibuffer, Up: Installation and Configuration 308 309 2.3 Completing in the Eshell or Shell 310 ===================================== 311 312 When completing in the Eshell I recommend conservative local settings 313 without auto completion, such that the completion behavior is similar to 314 widely used shells like Bash, Zsh or Fish. 315 316 (add-hook 'eshell-mode-hook 317 (lambda () 318 (setq-local corfu-auto nil) 319 (corfu-mode))) 320 321 When pressing ‘RET’ while the Corfu popup is visible, the 322 ‘corfu-insert’ command will be invoked. This command does inserts the 323 currently selected candidate, but it does not send the prompt input to 324 Eshell or the comint process. Therefore you often have to press ‘RET’ 325 twice which feels like an unnecessary double confirmation. Fortunately 326 it is easy to improve this! In my configuration I define the advice 327 ‘corfu-send-shell’ which sends the candidate after insertion. 328 329 (defun corfu-send-shell (&rest _) 330 "Send completion candidate when inside comint/eshell." 331 (cond 332 ((and (derived-mode-p 'eshell-mode) (fboundp 'eshell-send-input)) 333 (eshell-send-input)) 334 ((and (derived-mode-p 'comint-mode) (fboundp 'comint-send-input)) 335 (comint-send-input)))) 336 337 (advice-add #'corfu-insert :after #'corfu-send-shell) 338 339 Shell completion uses the flexible ‘Pcomplete’ mechanism internally, 340 which allows you to program the completions per shell command. If you 341 want to know more, look into this blog post 342 (https://www.masteringemacs.org/article/pcomplete-context-sensitive-completion-emacs), 343 which shows how to configure Pcomplete for git commands. I recommend 344 the pcmpl-args (https://github.com/JonWaltman/pcmpl-args.el) package 345 which extends Pcomplete with completion support and helpful annotation 346 support for more commands. Similar to the Fish shell, pcmpl-args uses 347 man page parsing and –help output parsing to dynamically generate 348 completions. This package brings Eshell completion to another level! 349 350 Unfortunately Pcomplete has a few technical issues, which we can work 351 around with the Cape (https://github.com/minad/cape) library (Completion 352 at point extensions). Cape provides wrappers, which sanitize the 353 Pcomplete function. Ideally the bugs in Pcomplete should be fixed 354 upstream. *For now these two advices are strongly recommended to 355 achieve a sane Eshell experience.* 356 357 ;; Silence the pcomplete capf, no errors or messages! 358 (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent) 359 360 ;; Ensure that pcomplete does not write to the buffer 361 ;; and behaves as a pure `completion-at-point-function'. 362 (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify) 363 364 365 File: docYXxwrO.info, Node: Orderless completion, Next: TAB-and-Go completion, Prev: Completing in the Eshell or Shell, Up: Installation and Configuration 366 367 2.4 Orderless completion 368 ======================== 369 370 Orderless (https://github.com/oantolin/orderless) is an advanced 371 completion style that supports multi-component search filters separated 372 by a configurable character (space, by default). Normally, entering 373 characters like space which lie outside the completion region boundaries 374 (words, typically) causes Corfu to quit. This behavior is helpful with 375 auto-completion, which may pop-up when not desired, e.g. on entering a 376 new variable name. Just keep typing and Corfu will get out of the way. 377 378 But orderless search terms can contain arbitrary characters; they are 379 also interpreted as regular expressions. To use orderless, set 380 ‘corfu-separator’ (a space, by default) to the primary character of your 381 orderless component separator. 382 383 Then, when a new orderless component is desired, use ‘M-SPC’ 384 (‘corfu-insert-separator’) to enter the _first_ component separator in 385 the input, and arbitrary orderless search terms and new separators can 386 be entered thereafter. 387 388 To treat the entire input as Orderless input, you can set the 389 customization option ‘corfu-quit-at-boundary=t’. This disables the 390 predicate which checks if the current completion boundary has been left. 391 In contrast, if you _always_ want to quit at the boundary, simply set 392 ‘corfu-quit-at-boundary=nil’. By default ‘corfu-quit-at-boundary’ is 393 set to ‘separator’ which quits at completion boundaries as long as no 394 separator has been inserted with ‘corfu-insert-separator’. 395 396 Finally, there exists the user option ‘corfu-quit-no-match’ which is 397 set to ‘separator’ by default. With this setting Corfu stays alive as 398 soon as you start advanced filtering with a ‘corfu-separator’ even if 399 there are no matches, for example due to a typo. As long as no 400 separator character has been inserted with ‘corfu-insert-separator’, 401 Corfu will still quit if there are no matches. This ensures that the 402 Corfu popup goes away quickly if completion is not possible. 403 404 In the following we show two configurations, one which works best 405 with auto completion and one which may work better with manual 406 completion if you prefer to always use ‘SPC’ to separate the Orderless 407 components. 408 409 ;; Auto completion example 410 (use-package corfu 411 :custom 412 (corfu-auto t) ;; Enable auto completion 413 ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space 414 :bind 415 ;; Another key binding can be used, such as S-SPC. 416 ;; (:map corfu-map ("M-SPC" . corfu-insert-separator)) 417 :init 418 (global-corfu-mode)) 419 420 ;; Manual completion example 421 (use-package corfu 422 :custom 423 ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space 424 :bind 425 ;; Configure SPC for separator insertion 426 (:map corfu-map ("SPC" . corfu-insert-separator)) 427 :init 428 (global-corfu-mode)) 429 430 431 File: docYXxwrO.info, Node: TAB-and-Go completion, Next: Transfer completion to the minibuffer, Prev: Orderless completion, Up: Installation and Configuration 432 433 2.5 TAB-and-Go completion 434 ========================= 435 436 You may be interested in configuring Corfu in TAB-and-Go style. 437 Pressing TAB moves to the next candidate and further input will then 438 commit the selection. Note that further input will not expand snippets 439 or templates, which may not be desired but which leads overall to a more 440 predictable behavior. In order to force snippet expansion, confirm a 441 candidate explicitly with ‘RET’. 442 443 (use-package corfu 444 ;; TAB-and-Go customizations 445 :custom 446 (corfu-cycle t) ;; Enable cycling for `corfu-next/previous' 447 (corfu-preselect-first nil) ;; Disable candidate preselection 448 449 ;; Use TAB for cycling, default is `corfu-complete'. 450 :bind 451 (:map corfu-map 452 ("TAB" . corfu-next) 453 ([tab] . corfu-next) 454 ("S-TAB" . corfu-previous) 455 ([backtab] . corfu-previous)) 456 457 :init 458 (global-corfu-mode)) 459 460 461 File: docYXxwrO.info, Node: Transfer completion to the minibuffer, Prev: TAB-and-Go completion, Up: Installation and Configuration 462 463 2.6 Transfer completion to the minibuffer 464 ========================================= 465 466 Sometimes it is useful to transfer the Corfu completion session to the 467 minibuffer, since the minibuffer offers richer interaction features. In 468 particular, Embark (https://github.com/oantolin/embark) is available in 469 the minibuffer, such that you can act on the candidates or 470 export/collect the candidates to a separate buffer. We could add Corfu 471 support to Embark in the future, such that export/collect is possible 472 directly from Corfu. But in my opinion having the ability to transfer 473 the Corfu completion to the minibuffer is an even better feature, since 474 further completion can be performed there. 475 476 The command ‘corfu-move-to-minibuffer’ is defined here in terms of 477 ‘consult-completion-in-region’, which uses the minibuffer completion UI 478 via ‘completing-read’. 479 480 (defun corfu-move-to-minibuffer () 481 (interactive) 482 (let ((completion-extra-properties corfu--extra) 483 completion-cycle-threshold completion-cycling) 484 (apply #'consult-completion-in-region completion-in-region--data))) 485 (define-key corfu-map "\M-m" #'corfu-move-to-minibuffer) 486 487 488 File: docYXxwrO.info, Node: Key bindings, Next: Extensions, Prev: Installation and Configuration, Up: Top 489 490 3 Key bindings 491 ************** 492 493 Corfu uses a transient keymap ‘corfu-map’ which is active while the 494 popup is shown. The keymap defines the following remappings and 495 bindings: 496 497 • ‘beginning-of-buffer’ -> ‘corfu-first’ 498 • ‘end-of-buffer’ -> ‘corfu-last’ 499 • ‘scroll-down-command’ -> ‘corfu-scroll-down’ 500 • ‘scroll-up-command’ -> ‘corfu-scroll-up’ 501 • ‘next-line’, ‘down’, ‘M-n’ -> ‘corfu-next’ 502 • ‘previous-line’, ‘up’, ‘M-p’ -> ‘corfu-previous’ 503 • ‘completion-at-point’, ‘TAB’ -> ‘corfu-complete’ 504 • ‘RET’ -> ‘corfu-insert’ 505 • ‘M-g’ -> ‘corfu-info-location’ 506 • ‘M-h’ -> ‘corfu-info-documentation’ 507 • ‘M-SPC’ -> ‘corfu-insert-separator’ 508 • ‘C-g’ -> ‘corfu-quit’ 509 • ‘keyboard-escape-quit’ -> ‘corfu-reset’ 510 511 512 File: docYXxwrO.info, Node: Extensions, Next: Complementary packages, Prev: Key bindings, Up: Top 513 514 4 Extensions 515 ************ 516 517 We maintain small extension packages to Corfu in this repository in the 518 subdirectory extensions/ 519 (https://github.com/minad/corfu/tree/main/extensions). The extensions 520 are installed together with Corfu if you pull the package from ELPA. 521 The extensions are inactive by default and can be enabled manually if 522 desired. Furthermore it is possible to install all of the files 523 separately, both ‘corfu.el’ and the ‘corfu-*.el’ extensions. Currently 524 the following extensions come with the Corfu ELPA package: 525 526 • corfu-echo 527 (https://github.com/minad/corfu/blob/main/extensions/corfu-echo.el): 528 ‘corfu-echo-mode’ displays a brief candidate documentation in the 529 echo area. 530 • corfu-history 531 (https://github.com/minad/corfu/blob/main/extensions/corfu-history.el): 532 ‘corfu-history-mode’ remembers selected candidates and sorts the 533 candidates by their history position. 534 • corfu-indexed 535 (https://github.com/minad/corfu/blob/main/extensions/corfu-indexed.el): 536 ‘corfu-indexed-mode’ allows you to select indexed candidates with 537 prefix arguments. 538 • corfu-info 539 (https://github.com/minad/corfu/blob/main/extensions/corfu-info.el): 540 Actions to access the candidate location and documentation. 541 • corfu-popupinfo 542 (https://github.com/minad/corfu/blob/main/extensions/corfu-popupinfo.el): 543 Display candidate documentation or source in a popup next to the 544 candidate menu. 545 • corfu-quick 546 (https://github.com/minad/corfu/blob/main/extensions/corfu-quick.el): 547 Commands to select using Avy-style quick keys. 548 549 See the Commentary of those files for configuration details. 550 551 552 File: docYXxwrO.info, Node: Complementary packages, Next: Alternatives, Prev: Extensions, Up: Top 553 554 5 Complementary packages 555 ************************ 556 557 Corfu works well together with all packages providing code completion 558 via the ‘completion-at-point-functions’. Many modes and packages 559 already provide a Capf out of the box. Nevertheless you may want to 560 look into complementary packages to enhance your setup. 561 562 • corfu-terminal (https://codeberg.org/akib/emacs-corfu-terminal): 563 The corfu-terminal package provides an overlay-based display for 564 Corfu, such that you can use Corfu in terminal Emacs. 565 566 • Orderless (https://github.com/oantolin/orderless): Corfu supports 567 completion styles, including the advanced Orderless 568 (https://github.com/oantolin/orderless) completion style, where the 569 filtering expressions are separated by spaces or another character 570 (see ‘corfu-separator’). 571 572 • Cape (https://github.com/minad/cape): Additional Capf backends and 573 ‘completion-in-region’ commands are provided by the Cape 574 (https://github.com/minad/cape) package. Among others, the package 575 supplies a file path and a Dabbrev completion backend. Cape 576 provides the ‘cape-company-to-capf’ adapter to reuse Company 577 backends in Corfu. Furthermore the function ‘cape-super-capf’ can 578 merge multiple Capfs, such that the candidates of multiple Capfs 579 are displayed together at the same time. 580 581 • kind-icon (https://github.com/jdtsmith/kind-icon): Icons are 582 supported by Corfu via an external package. For example the 583 kind-icon (https://github.com/jdtsmith/kind-icon) package provides 584 beautifully styled SVG icons based on monochromatic icon sets like 585 material design. 586 587 • pcmpl-args (https://github.com/JonWaltman/pcmpl-args.el): Extend 588 the Eshell/Shell Pcomplete mechanism with support for many more 589 commands. Similar to the Fish shell, Pcomplete uses man page 590 parsing to dynamically retrieve the completions and helpful 591 annotations. This package brings Eshell completions to another 592 level! 593 594 • Tempel (https://github.com/minad/tempel): Tiny template/snippet 595 package with templates in Lisp syntax, which can be used in 596 conjunction with Corfu. 597 598 • Vertico (https://github.com/minad/vertico): You may also want to 599 look into my Vertico (https://github.com/minad/vertico) package. 600 Vertico is the minibuffer completion counterpart of Corfu. 601 602 603 File: docYXxwrO.info, Node: Alternatives, Next: Contributions, Prev: Complementary packages, Up: Top 604 605 6 Alternatives 606 ************** 607 608 • Company (https://github.com/company-mode/company-mode): Company is 609 a widely used and mature completion package, which implements a 610 similar interaction model and popup UI as Corfu. While Corfu 611 relies exclusively on the standard Emacs completion API (Capfs), 612 Company defines its own API for the backends. Company includes its 613 completion backends, which are incompatible with the Emacs 614 completion infrastructure. As a result of this design, Company is 615 a more complex package than Corfu. Company by default uses 616 overlays for the popup in contrast to the child frames used by 617 Corfu. Overall both packages work well, but Company integrates 618 less tightly with Emacs. The ‘completion-styles’ support is more 619 limited and the ‘completion-at-point’ command and the 620 ‘completion-in-region’ function do not invoke Company. 621 622 • Mct (https://git.sr.ht/~protesilaos/mct): Protesilaos’ Minibuffer 623 Confines Transcended package supports both minibuffer completion 624 and completion in region. It reuses the default completion UI for 625 this purpose and installs a timer which live updates the completion 626 buffer. The main advantage of Mct is that you work with a regular 627 Emacs buffer instead of with a popup. You can take advantage of 628 the usual Emacs commands to navigate in the completions buffer. On 629 top, Mct enhances the movement such that you can quickly switch 630 between the completions buffer and the minibuffer or the region 631 which is being completed. Mct does not support timer-based auto 632 completion, but the integration into Emacs is naturally tight. 633 Note that Mct development is currently discontinued 634 (https://protesilaos.com/codelog/2022-04-14-emacs-discontinue-mct/) 635 due to recent changes of the default completion UI on the Emacs 636 master branch. 637 638 • consult-completion-in-region (https://github.com/minad/consult): 639 The Consult package provides the function 640 ‘consult-completion-in-region’ which can be set as 641 ‘completion-in-region-function’ such that it handles 642 ‘completion-at-point’. The function works by transferring the 643 in-buffer completion to the minibuffer. In the minibuffer, the 644 minibuffer completion UI, for example Vertico 645 (https://github.com/minad/vertico) takes over. If you prefer to 646 perform all your completions in the minibuffer 647 ‘consult-completion-in-region’ is your best option. 648 649 650 File: docYXxwrO.info, Node: Contributions, Prev: Alternatives, Up: Top 651 652 7 Contributions 653 *************** 654 655 Since this package is part of GNU ELPA 656 (https://elpa.gnu.org/packages/corfu.html) contributions require a 657 copyright assignment to the FSF. 658 659 660 661 Tag Table: 662 Node: Top213 663 Node: Features2134 664 Node: Installation and Configuration3616 665 Node: Auto completion9300 666 Node: Completing in the minibuffer11668 667 Node: Completing in the Eshell or Shell13743 668 Node: Orderless completion16608 669 Node: TAB-and-Go completion19709 670 Node: Transfer completion to the minibuffer20828 671 Node: Key bindings22149 672 Node: Extensions23144 673 Node: Complementary packages24944 674 Node: Alternatives27449 675 Node: Contributions30100 676 677 End Tag Table 678 679 680 Local Variables: 681 coding: utf-8 682 End: