corfu.info (35379B)
1 This is docxDqOT0.info, produced by makeinfo version 6.8 from 2 corfu.texi. 3 4 INFO-DIR-SECTION Emacs misc features 5 START-INFO-DIR-ENTRY 6 * Corfu: (corfu). COmpletion in Region FUnction. 7 END-INFO-DIR-ENTRY 8 9 10 File: docxDqOT0.info, Node: Top, Next: Features, Up: (dir) 11 12 corfu.el - COmpletion in Region FUnction 13 **************************************** 14 15 Corfu enhances in-buffer completion with a small completion popup. The 16 current candidates are shown in a popup below or above the point. The 17 candidates can be selected by moving up and down. Corfu is the 18 minimalistic in-buffer completion counterpart of the Vertico 19 (https://github.com/minad/vertico) minibuffer UI. 20 21 Corfu is a small package, which relies on the Emacs completion 22 facilities and concentrates on providing a polished completion UI. 23 In-buffer completion UIs in Emacs can hook into ‘completion-in-region’, 24 which implements the interaction with the user. Completions at point 25 are either provided by commands like ‘dabbrev-completion’ or by 26 pluggable backends (‘completion-at-point-functions’, Capfs) and are then 27 passed to ‘completion-in-region’. Many programming, text and shell 28 major modes implement a Capf. Corfu does not include its own completion 29 backends. The Emacs built-in Capfs and the Capfs provided by 30 third-party programming language packages are often sufficient. 31 Additional Capfs and completion utilities are provided by the Cape 32 (https://github.com/minad/cape) package. 33 34 *NOTE*: Corfu uses child frames to show the popup and falls back to 35 the default setting of the ‘completion-in-region-function’ on 36 non-graphical displays. If you want to use Corfu in the terminal, 37 install the package corfu-terminal 38 (https://codeberg.org/akib/emacs-corfu-terminal), which provides an 39 alternative overlay-based display. 40 41 * Menu: 42 43 * Features:: 44 * Installation:: 45 * Key bindings:: 46 * Configuration:: 47 * Extensions:: 48 * Complementary packages:: 49 * Alternatives:: 50 * Debugging Corfu:: 51 * Contributions:: 52 53 — The Detailed Node Listing — 54 55 Configuration 56 57 * Auto completion:: 58 * Completing in the minibuffer:: 59 * Completing in the Eshell or Shell:: 60 * Orderless completion:: 61 * TAB-only completion:: 62 * TAB-and-Go completion:: 63 * Expanding to the common candidate prefix with TAB:: 64 * Transfer completion to the minibuffer:: 65 66 67 68 File: docxDqOT0.info, Node: Features, Next: Installation, Prev: Top, Up: Top 69 70 1 Features 71 ********** 72 73 • Timer-based auto-completions (_off_ by default, set ‘corfu-auto’). 74 • Popup display with scrollbar indicator and arrow key navigation. 75 • The popup can be summoned explicitly by pressing ‘TAB’ at any time. 76 • The current candidate is inserted with ‘TAB’ and selected with 77 ‘RET’. 78 • Candidate sorting by prefix, string length and alphabetically. 79 • The selected candidate is previewed (configurable via 80 ‘corfu-preview-current’). 81 • The selected candidate is automatically committed on further input 82 by default. (configurable via ‘corfu-preview-current’). 83 • Supports the Orderless (https://github.com/oantolin/orderless) 84 completion style. The filter string can contain arbitrary 85 characters, after inserting a space via ‘M-SPC’ (configurable via 86 ‘corfu-quit-at-boundary’ and ‘corfu-separator’). 87 • Lazy completion candidate highlighting for performance. 88 • Support for candidate annotations (‘annotation-function’, 89 ‘affixation-function’). 90 • Deprecated candidates are displayed as crossed out. 91 • Icons can be provided by an external package via margin formatter 92 functions. 93 • Rich set of extensions: Quick keys, Index keys, Sorting by history, 94 Candidate documentation in echo area, popup or separate buffer. 95 96 97 File: docxDqOT0.info, Node: Installation, Next: Key bindings, Prev: Features, Up: Top 98 99 2 Installation 100 ************** 101 102 Corfu is available from GNU ELPA 103 (https://elpa.gnu.org/packages/corfu.html). You can install it directly 104 via ‘M-x package-install RET corfu RET’. After installation, activate 105 the global minor mode with ‘M-x global-corfu-mode RET’. Set the 106 variable ‘corfu-auto’ to t in order to enable auto completion. For 107 manual completion press ‘M-TAB’ (or ‘TAB’) within a buffer. 108 109 110 File: docxDqOT0.info, Node: Key bindings, Next: Configuration, Prev: Installation, Up: Top 111 112 3 Key bindings 113 ************** 114 115 Corfu uses a transient keymap ‘corfu-map’ which is active while the 116 popup is shown. The keymap defines the following remappings of 117 fundamental commands and bindings: 118 119 Binding/Remapping Corfu command 120 ------------------------------------------------------------ 121 ‘move-beginning-of-line’ ‘corfu-prompt-beginning’ 122 ‘move-end-of-line’ ‘corfu-prompt-end’ 123 ‘beginning-of-buffer’ ‘corfu-first’ 124 ‘end-of-buffer’ ‘corfu-last’ 125 ‘scroll-down-command’ ‘corfu-scroll-down’ 126 ‘scroll-up-command’ ‘corfu-scroll-up’ 127 ‘next-line’, ‘down’, ‘M-n’ ‘corfu-next’ 128 ‘previous-line’, ‘up’, ‘M-p’ ‘corfu-previous’ 129 ‘completion-at-point’, ‘TAB’ ‘corfu-complete’ 130 ‘M-TAB’ ‘corfu-expand’ 131 ‘RET’ ‘corfu-insert’ 132 ‘M-g’ ‘corfu-info-location’ 133 ‘M-h’ ‘corfu-info-documentation’ 134 ‘M-SPC’ ‘corfu-insert-separator’ 135 ‘C-g’ ‘corfu-quit’ 136 ‘keyboard-escape-quit’ ‘corfu-reset’ 137 138 139 File: docxDqOT0.info, Node: Configuration, Next: Extensions, Prev: Key bindings, Up: Top 140 141 4 Configuration 142 *************** 143 144 In order to configure Corfu and other packages in your init.el, you may 145 want to use ‘use-package’. Corfu is flexibly customizable via ‘corfu-*’ 146 customization variables, such that you can adapt it precisely to your 147 requirements. However in order to quickly try out the Corfu completion 148 package, it should be sufficient to activate ‘global-corfu-mode’. You 149 can experiment with manual completion for example in an Elisp buffer or 150 in an Eshell or Shell buffer. For auto completion, set ‘corfu-auto’ to 151 t before turning on ‘global-corfu-mode’. 152 153 Here is an example configuration: 154 155 (use-package corfu 156 ;; Optional customizations 157 ;; :custom 158 ;; (corfu-cycle t) ;; Enable cycling for `corfu-next/previous' 159 ;; (corfu-auto t) ;; Enable auto completion 160 ;; (corfu-separator ?\s) ;; Orderless field separator 161 ;; (corfu-quit-at-boundary nil) ;; Never quit at completion boundary 162 ;; (corfu-quit-no-match nil) ;; Never quit, even if there is no match 163 ;; (corfu-preview-current nil) ;; Disable current candidate preview 164 ;; (corfu-preselect 'prompt) ;; Preselect the prompt 165 ;; (corfu-on-exact-match nil) ;; Configure handling of exact matches 166 ;; (corfu-scroll-margin 5) ;; Use scroll margin 167 168 ;; Enable Corfu only for certain modes. 169 ;; :hook ((prog-mode . corfu-mode) 170 ;; (shell-mode . corfu-mode) 171 ;; (eshell-mode . corfu-mode)) 172 173 ;; Recommended: Enable Corfu globally. This is recommended since Dabbrev can 174 ;; be used globally (M-/). See also the customization variable 175 ;; `global-corfu-modes' to exclude certain modes. 176 :init 177 (global-corfu-mode)) 178 179 ;; A few more useful configurations... 180 (use-package emacs 181 :init 182 ;; TAB cycle if there are only few candidates 183 ;; (setq completion-cycle-threshold 3) 184 185 ;; Enable indentation+completion using the TAB key. 186 ;; `completion-at-point' is often bound to M-TAB. 187 (setq tab-always-indent 'complete) 188 189 ;; Emacs 30 and newer: Disable Ispell completion function. As an alternative, 190 ;; try `cape-dict'. 191 (setq text-mode-ispell-word-completion nil) 192 193 ;; Emacs 28 and newer: Hide commands in M-x which do not apply to the current 194 ;; mode. Corfu commands are hidden, since they are not used via M-x. This 195 ;; setting is useful beyond Corfu. 196 (setq read-extended-command-predicate #'command-completion-default-include-p)) 197 198 Dabbrev completion is based on ‘completion-in-region’ and can be used 199 with Corfu. You may want to swap the ‘dabbrev-completion’ with the 200 ‘dabbrev-expand’ key for easier access, if you prefer completion. Also 201 take a look at the ‘cape-dabbrev’ completion at point function provided 202 by my Cape (https://github.com/minad/cape) package. 203 204 ;; Use Dabbrev with Corfu! 205 (use-package dabbrev 206 ;; Swap M-/ and C-M-/ 207 :bind (("M-/" . dabbrev-completion) 208 ("C-M-/" . dabbrev-expand)) 209 :config 210 (add-to-list 'dabbrev-ignored-buffer-regexps "\\` ") 211 ;; Since 29.1, use `dabbrev-ignored-buffer-regexps' on older. 212 (add-to-list 'dabbrev-ignored-buffer-modes 'doc-view-mode) 213 (add-to-list 'dabbrev-ignored-buffer-modes 'pdf-view-mode)) 214 215 If you start to configure the package more deeply, I recommend to 216 give the Orderless completion style a try for filtering. Orderless 217 completion is different from the familiar prefix TAB completion. Corfu 218 can be used with the default completion styles. The use of Orderless is 219 not a necessity. 220 221 ;; Optionally use the `orderless' completion style. 222 (use-package orderless 223 :init 224 ;; Configure a custom style dispatcher (see the Consult wiki) 225 ;; (setq orderless-style-dispatchers '(+orderless-dispatch) 226 ;; orderless-component-separator #'orderless-escapable-split-on-space) 227 (setq completion-styles '(orderless basic) 228 completion-category-defaults nil 229 completion-category-overrides '((file (styles partial-completion))))) 230 231 The ‘basic’ completion style is specified as fallback in addition to 232 ‘orderless’ in order to ensure that completion commands which rely on 233 dynamic completion tables, e.g., ‘completion-table-dynamic’ or 234 ‘completion-table-in-turn’, work correctly. See ‘+orderless-dispatch’ 235 in the Consult wiki (https://github.com/minad/consult/wiki) for an 236 advanced Orderless style dispatcher. Additionally enable 237 ‘partial-completion’ for file path expansion. ‘partial-completion’ is 238 important for file wildcard support. Multiple files can be opened at 239 once with ‘find-file’ if you enter a wildcard. You may also give the 240 ‘initials’ completion style a try. 241 242 See also the Corfu Wiki (https://github.com/minad/corfu/wiki) and the 243 Cape manual (https://github.com/minad/cape) for additional Capf 244 configuration tips. For more general documentation read the chapter 245 about completion in the Emacs manual 246 (https://www.gnu.org/software/emacs/manual/html_node/emacs/Completion.html). 247 If you want to create your own Capfs, you can find documentation about 248 completion in the Elisp manual 249 (https://www.gnu.org/software/emacs/manual/html_node/elisp/Completion.html). 250 251 * Menu: 252 253 * Auto completion:: 254 * Completing in the minibuffer:: 255 * Completing in the Eshell or Shell:: 256 * Orderless completion:: 257 * TAB-only completion:: 258 * TAB-and-Go completion:: 259 * Expanding to the common candidate prefix with TAB:: 260 * Transfer completion to the minibuffer:: 261 262 263 File: docxDqOT0.info, Node: Auto completion, Next: Completing in the minibuffer, Up: Configuration 264 265 4.1 Auto completion 266 =================== 267 268 Auto completion is disabled by default, but can be enabled by setting 269 ‘corfu-auto’ to t. Furthermore you may want to configure Corfu to quit 270 completion eagerly, such that the completion popup stays out of your way 271 when it appeared unexpectedly. 272 273 ;; Enable auto completion and configure quitting 274 (setq corfu-auto t 275 corfu-quit-no-match 'separator) ;; or t 276 277 I suggest to experiment with the various settings and key bindings to 278 find a configuration which works for you. There is no one perfect 279 configuration which fits all. Some people like auto completion, some 280 like manual completion, some want to cycle with TAB and some with the 281 arrow keys. 282 283 In case you like auto completion settings, where the completion popup 284 appears immediately, better use a cheap completion style like ‘basic’, 285 which performs prefix filtering. In this case Corfu completion should 286 still be fast in buffers with efficient completion backends. You can 287 try the following settings in an Elisp buffer or the Emacs scratch 288 buffer. Note that such settings can slow down Emacs due to the high 289 load on the Lisp runtime and garbage collector. 290 291 (setq-local corfu-auto t 292 corfu-auto-delay 0 ;; TOO SMALL - NOT RECOMMENDED 293 corfu-auto-prefix 1 ;; TOO SMALL - NOT RECOMMENDED 294 completion-styles '(basic)) 295 296 If you want to combine fast prefix filtering and Orderless filtering 297 you can still do that by defining a custom Orderless completion style 298 via ‘orderless-define-completion-style’. We use a custom style 299 dispatcher, which enables efficient prefix filtering for input shorter 300 than 4 characters. Note that such a setup is advanced. Please refer to 301 the Orderless documentation and source code for further details. 302 303 (defun orderless-fast-dispatch (word index total) 304 (and (= index 0) (= total 1) (length< word 4) 305 (cons 'orderless-literal-prefix word)))) 306 307 (orderless-define-completion-style orderless-fast 308 (orderless-style-dispatchers '(orderless-fast-dispatch)) 309 (orderless-matching-styles '(orderless-literal orderless-regexp))) 310 311 (setq-local corfu-auto t 312 corfu-auto-delay 0 ;; TOO SMALL - NOT RECOMMENDED 313 corfu-auto-prefix 1 ;; TOO SMALL - NOT RECOMMENDED 314 completion-styles '(orderless-fast basic)) 315 316 317 File: docxDqOT0.info, Node: Completing in the minibuffer, Next: Completing in the Eshell or Shell, Prev: Auto completion, Up: Configuration 318 319 4.2 Completing in the minibuffer 320 ================================ 321 322 Corfu can be used for completion in the minibuffer, since it relies on 323 child frames to display the candidates. The Corfu popup can be shown 324 even if it doesn’t fully fit inside the minibuffer. 325 326 By default, ‘global-corfu-mode’ does not activate ‘corfu-mode’ in the 327 minibuffer, to avoid interference with specialised minibuffer completion 328 UIs like Vertico or Mct. However you may still want to enable Corfu 329 completion for commands like ‘M-:’ (‘eval-expression’) or ‘M-!’ 330 (‘shell-command’), which read from the minibuffer. In order to detect 331 minibuffers with completion we check if the variable 332 ‘completion-at-point-functions’ is set locally. 333 334 (defun corfu-enable-in-minibuffer () 335 "Enable Corfu in the minibuffer." 336 (when (local-variable-p 'completion-at-point-functions) 337 ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion 338 (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup 339 corfu-popupinfo-delay nil) 340 (corfu-mode 1))) 341 (add-hook 'minibuffer-setup-hook #'corfu-enable-in-minibuffer) 342 343 This is not recommended, but one can also enable Corfu more generally 344 for every minibuffer, as long as no completion UI is active. In the 345 following example we check for Mct and Vertico. Furthermore we ensure 346 that Corfu is not enabled if a password is read from the minibuffer. 347 348 (defun corfu-enable-always-in-minibuffer () 349 "Enable Corfu in the minibuffer if Vertico/Mct are not active." 350 (unless (or (bound-and-true-p mct--active) 351 (bound-and-true-p vertico--input) 352 (eq (current-local-map) read-passwd-map)) 353 ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion 354 (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup 355 corfu-popupinfo-delay nil) 356 (corfu-mode 1))) 357 (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1) 358 359 360 File: docxDqOT0.info, Node: Completing in the Eshell or Shell, Next: Orderless completion, Prev: Completing in the minibuffer, Up: Configuration 361 362 4.3 Completing in the Eshell or Shell 363 ===================================== 364 365 When completing in the Eshell I recommend conservative local settings 366 without auto completion, such that the completion behavior is similar to 367 widely used shells like Bash, Zsh or Fish. 368 369 (add-hook 'eshell-mode-hook 370 (lambda () 371 (setq-local corfu-auto nil) 372 (corfu-mode))) 373 374 When pressing ‘RET’ while the Corfu popup is visible, the 375 ‘corfu-insert’ command will be invoked. This command does inserts the 376 currently selected candidate, but it does not send the prompt input to 377 Eshell or the Comint process. Therefore you often have to press ‘RET’ 378 twice which feels like an unnecessary double confirmation. Fortunately 379 it is easy to improve this! In my configuration I define the advice 380 ‘corfu-send-shell’ which sends the candidate after insertion. 381 382 (defun corfu-send-shell (&rest _) 383 "Send completion candidate when inside comint/eshell." 384 (cond 385 ((and (derived-mode-p 'eshell-mode) (fboundp 'eshell-send-input)) 386 (eshell-send-input)) 387 ((and (derived-mode-p 'comint-mode) (fboundp 'comint-send-input)) 388 (comint-send-input)))) 389 390 (advice-add #'corfu-insert :after #'corfu-send-shell) 391 392 Shell completion uses the flexible Pcomplete mechanism internally, 393 which allows you to program the completions per shell command. If you 394 want to know more, look into this blog post 395 (https://www.masteringemacs.org/article/pcomplete-context-sensitive-completion-emacs), 396 which shows how to configure Pcomplete for git commands. Since Emacs 397 29, Pcomplete offers the ‘pcomplete-from-help’ function which parses the 398 ‘--help’ output of a command and produces completions for command line 399 options. 400 401 Pcomplete has a few bugs on Emacs 28 and older. We can work around 402 the issues with the Cape (https://github.com/minad/cape) library 403 (Completion at point extensions). Cape provides wrappers which sanitize 404 the Pcomplete function. If you use Emacs 28 or older installing these 405 advices is recommended such that Pcomplete works properly. On Emacs 29 406 the advices should not be necessary anymore, since most relevant bugs 407 have been fixed. I therefore recommend to avoid the advices on Emacs 29 408 and eventually report any remaining Pcomplete issues upstream. 409 410 ;; The advices are only needed on Emacs 28 and older. 411 (when (< emacs-major-version 29) 412 ;; Silence the pcomplete capf. Hide errors or messages. 413 (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent) 414 415 ;; Ensure that pcomplete does not write to the buffer and behaves as a 416 ;; `completion-at-point-function' without side-effects. 417 (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify)) 418 419 420 File: docxDqOT0.info, Node: Orderless completion, Next: TAB-only completion, Prev: Completing in the Eshell or Shell, Up: Configuration 421 422 4.4 Orderless completion 423 ======================== 424 425 Orderless (https://github.com/oantolin/orderless) is an advanced 426 completion style that supports multi-component search filters separated 427 by a configurable character (space, by default). Normally, entering 428 characters like space which lie outside the completion region boundaries 429 (words, typically) causes Corfu to quit. This behavior is helpful with 430 auto-completion, which may pop-up when not desired, e.g. on entering a 431 new variable name. Just keep typing and Corfu will get out of the way. 432 433 But orderless search terms can contain arbitrary characters; they are 434 also interpreted as regular expressions. To use orderless, set 435 ‘corfu-separator’ (a space, by default) to the primary character of your 436 orderless component separator. 437 438 Then, when a new orderless component is desired, use ‘M-SPC’ 439 (‘corfu-insert-separator’) to enter the first component separator in the 440 input, and arbitrary orderless search terms and new separators can be 441 entered thereafter. 442 443 To treat the entire input as Orderless input, you can set the 444 customization option ‘corfu-quit-at-boundary’ to nil. This disables the 445 predicate which checks if the current completion boundary has been left. 446 In contrast, if you always want to quit at the boundary, set 447 ‘corfu-quit-at-boundary’ to t. By default ‘corfu-quit-at-boundary’ is 448 set to ‘separator’ which quits at completion boundaries as long as no 449 separator has been inserted with ‘corfu-insert-separator’. 450 451 Finally, there exists the user option ‘corfu-quit-no-match’ which is 452 set to ‘separator’ by default. With this setting Corfu stays alive as 453 soon as you start advanced filtering with a ‘corfu-separator’ even if 454 there are no matches, for example due to a typo. As long as no 455 separator character has been inserted with ‘corfu-insert-separator’, 456 Corfu will still quit if there are no matches. This ensures that the 457 Corfu popup goes away quickly if completion is not possible. 458 459 In the following we show two configurations, one which works best 460 with auto completion and one which may work better with manual 461 completion if you prefer to always use ‘SPC’ to separate the Orderless 462 components. 463 464 ;; Auto completion example 465 (use-package corfu 466 :custom 467 (corfu-auto t) ;; Enable auto completion 468 ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space 469 :bind 470 ;; Another key binding can be used, such as S-SPC. 471 ;; (:map corfu-map ("M-SPC" . corfu-insert-separator)) 472 :init 473 (global-corfu-mode)) 474 475 ;; Manual completion example 476 (use-package corfu 477 :custom 478 ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space 479 :bind 480 ;; Configure SPC for separator insertion 481 (:map corfu-map ("SPC" . corfu-insert-separator)) 482 :init 483 (global-corfu-mode)) 484 485 486 File: docxDqOT0.info, Node: TAB-only completion, Next: TAB-and-Go completion, Prev: Orderless completion, Up: Configuration 487 488 4.5 TAB-only completion 489 ======================= 490 491 By default, Corfu steals both the ‘RET’ and ‘TAB’ keys, when the Corfu 492 popup is open. This can feel intrusive, in particular in combination 493 with auto completion. ‘RET’ may accidentally commit an automatically 494 selected candidate, while you actually wanted to start a new line. As 495 an alternative we can unbind the ‘RET’ key completely from ‘corfu-map’ 496 or reserve the ‘RET’ key only in shell modes. 497 498 ;; TAB-only configuration 499 (use-package corfu 500 :custom 501 (corfu-auto t) ;; Enable auto completion 502 (corfu-preselect 'directory) ;; Select the first candidate, except for directories 503 504 ;; Free the RET key for less intrusive behavior. 505 :bind 506 (:map corfu-map 507 ;; Option 1: Unbind RET completely 508 ;;; ("RET" . nil) 509 ;; Option 2: Use RET only in shell modes 510 ("RET" . (menu-item "" nil :filter corfu-insert-shell-filter))) 511 512 :init 513 (global-corfu-mode)) 514 515 (defun corfu-insert-shell-filter (&optional _) 516 "Insert completion candidate and send when inside comint/eshell." 517 (when (or (derived-mode-p 'eshell-mode) (derived-mode-p 'comint-mode)) 518 (lambda () 519 (interactive) 520 (corfu-insert) 521 ;; `corfu-send-shell' was defined above 522 (corfu-send-shell)))) 523 524 525 File: docxDqOT0.info, Node: TAB-and-Go completion, Next: Expanding to the common candidate prefix with TAB, Prev: TAB-only completion, Up: Configuration 526 527 4.6 TAB-and-Go completion 528 ========================= 529 530 You may be interested in configuring Corfu in TAB-and-Go style. 531 Pressing TAB moves to the next candidate and further input will then 532 commit the selection. Note that further input will not expand snippets 533 or templates, which may not be desired but which leads overall to a more 534 predictable behavior. In order to force snippet expansion, confirm a 535 candidate explicitly with ‘RET’. 536 537 (use-package corfu 538 ;; TAB-and-Go customizations 539 :custom 540 (corfu-cycle t) ;; Enable cycling for `corfu-next/previous' 541 (corfu-preselect 'prompt) ;; Always preselect the prompt 542 543 ;; Use TAB for cycling, default is `corfu-complete'. 544 :bind 545 (:map corfu-map 546 ("TAB" . corfu-next) 547 ([tab] . corfu-next) 548 ("S-TAB" . corfu-previous) 549 ([backtab] . corfu-previous)) 550 551 :init 552 (global-corfu-mode)) 553 554 555 File: docxDqOT0.info, Node: Expanding to the common candidate prefix with TAB, Next: Transfer completion to the minibuffer, Prev: TAB-and-Go completion, Up: Configuration 556 557 4.7 Expanding to the common candidate prefix with TAB 558 ===================================================== 559 560 If you leave the default configuration of the completion styles, such 561 that the ‘basic’ completion style is still present, then pressing 562 ‘M-TAB’ (‘corfu-expand’) will expand the current input to the common 563 prefix of all completion candidates. In contrast, ‘TAB’ 564 (‘corfu-complete’) behaves differently and expands input to the 565 currently selected candidate. 566 567 If you use the ‘orderless’ completion style, then expansion works 568 differently by default. Orderless only expands to single matching 569 candidates, since due to its multi-component input, there does not 570 necessarily exist an expansion to a common candidate prefix. However it 571 is possible to define a separate ‘tab’ completion style. The ‘tab’ 572 completion style will only take over ‘TAB’ completion (if prefix 573 expansion is possible), but besides that won’t affect Orderless 574 candidate filtering. 575 576 (add-to-list 'completion-styles-alist 577 '(tab completion-basic-try-completion ignore 578 "Completion style which provides TAB completion only.")) 579 (setq completion-styles '(tab orderless basic))) 580 581 582 File: docxDqOT0.info, Node: Transfer completion to the minibuffer, Prev: Expanding to the common candidate prefix with TAB, Up: Configuration 583 584 4.8 Transfer completion to the minibuffer 585 ========================================= 586 587 Sometimes it is useful to transfer the Corfu completion session to the 588 minibuffer, since the minibuffer offers richer interaction features. In 589 particular, Embark (https://github.com/oantolin/embark) is available in 590 the minibuffer, such that you can act on the candidates or 591 export/collect the candidates to a separate buffer. We could add Corfu 592 support to Embark in the future, such that export or collect is possible 593 directly from Corfu. Nevertheless, the ability to transfer the Corfu 594 completion to the minibuffer is even more powerful, since further 595 completion is possible. 596 597 The command ‘corfu-move-to-minibuffer’ is defined here in terms of 598 ‘consult-completion-in-region’, which uses the minibuffer completion UI 599 via ‘completing-read’. 600 601 (defun corfu-move-to-minibuffer () 602 (interactive) 603 (pcase completion-in-region--data 604 (`(,beg ,end ,table ,pred ,extras) 605 (let ((completion-extra-properties extras) 606 completion-cycle-threshold completion-cycling) 607 (consult-completion-in-region beg end table pred))))) 608 (keymap-set corfu-map "M-m" #'corfu-move-to-minibuffer) 609 (add-to-list 'corfu-continue-commands #'corfu-move-to-minibuffer) 610 611 612 File: docxDqOT0.info, Node: Extensions, Next: Complementary packages, Prev: Configuration, Up: Top 613 614 5 Extensions 615 ************ 616 617 We maintain small extension packages to Corfu in this repository in the 618 subdirectory extensions/ 619 (https://github.com/minad/corfu/tree/main/extensions). The extensions 620 are installed together with Corfu if you pull the package from ELPA. 621 The extensions are inactive by default and can be enabled manually if 622 desired. Furthermore it is possible to install all of the files 623 separately, both ‘corfu.el’ and the ‘corfu-*.el’ extensions. Currently 624 the following extensions come with the Corfu ELPA package: 625 626 • corfu-echo 627 (https://github.com/minad/corfu/blob/main/extensions/corfu-echo.el): 628 ‘corfu-echo-mode’ displays a brief candidate documentation in the 629 echo area. 630 • corfu-history 631 (https://github.com/minad/corfu/blob/main/extensions/corfu-history.el): 632 ‘corfu-history-mode’ remembers selected candidates and sorts the 633 candidates by their history position. 634 • corfu-indexed 635 (https://github.com/minad/corfu/blob/main/extensions/corfu-indexed.el): 636 ‘corfu-indexed-mode’ allows you to select indexed candidates with 637 prefix arguments. 638 • corfu-info 639 (https://github.com/minad/corfu/blob/main/extensions/corfu-info.el): 640 Actions to access the candidate location and documentation. 641 • corfu-popupinfo 642 (https://github.com/minad/corfu/blob/main/extensions/corfu-popupinfo.el): 643 Display candidate documentation or source in a popup next to the 644 candidate menu. 645 • corfu-quick 646 (https://github.com/minad/corfu/blob/main/extensions/corfu-quick.el): 647 Commands to select using Avy-style quick keys. 648 649 See the Commentary of those files for configuration details. 650 651 652 File: docxDqOT0.info, Node: Complementary packages, Next: Alternatives, Prev: Extensions, Up: Top 653 654 6 Complementary packages 655 ************************ 656 657 Corfu works well together with all packages providing code completion 658 via the ‘completion-at-point-functions’. Many modes and packages 659 already provide a Capf out of the box. Nevertheless you may want to 660 look into complementary packages to enhance your setup. 661 662 • corfu-terminal (https://codeberg.org/akib/emacs-corfu-terminal): 663 The corfu-terminal package provides an overlay-based display for 664 Corfu, such that you can use Corfu in terminal Emacs. 665 666 • corfu-candidate-overlay 667 (https://code.bsdgeek.org/adam/corfu-candidate-overlay): Shows 668 as-you-type auto-suggestion candidate overlay with a visual 669 indication of whether there are many or exactly one candidate 670 available (works only with ‘corfu-auto’ disabled). 671 672 • Orderless (https://github.com/oantolin/orderless): Corfu supports 673 completion styles, including the advanced ‘orderless’ completion 674 style, where the filter expressions are separated by spaces or 675 another character (see ‘corfu-separator’). 676 677 • Cape (https://github.com/minad/cape): Provides additional Capf 678 backends and ‘completion-in-region’ commands. Among others, the 679 package supplies the file completion backend ‘cape-file’ and the 680 Dabbrev backend ‘cape-dabbrev’. Cape provides the 681 ‘cape-company-to-capf’ adapter to reuse Company backends in Corfu. 682 683 • nerd-icons-corfu (https://github.com/LuigiPiucco/nerd-icons-corfu), 684 kind-icon (https://github.com/jdtsmith/kind-icon): Icons are 685 supported by Corfu via external packages. The nerd-icons-corfu 686 package relies on the Nerd icon font, which is even supported on 687 terminal, while kind-icon uses SVGs from monochromatic icon sets. 688 689 • Tempel (https://github.com/minad/tempel): Tiny template/snippet 690 package with templates in Lisp syntax, which can be used in 691 conjunction with Corfu. 692 693 • Vertico (https://github.com/minad/vertico): You may also want to 694 look into my Vertico package. Vertico is the minibuffer completion 695 counterpart of Corfu. 696 697 698 File: docxDqOT0.info, Node: Alternatives, Next: Debugging Corfu, Prev: Complementary packages, Up: Top 699 700 7 Alternatives 701 ************** 702 703 • Company (https://github.com/company-mode/company-mode): Company is 704 a widely used and mature completion package, which implements a 705 similar UI as Corfu. While Corfu relies exclusively on the 706 standard Emacs completion API (Capfs), Company defines its own API 707 for the backends. Company includes its own completion backends, 708 following its own API, which are incompatible with the Emacs 709 completion infrastructure. Company provides an adapter 710 ‘company-capf’ to handle Capfs as a Company backend. As a result 711 of this design, Company is a more complex package than Corfu. 712 Company by default uses overlays for the popup in contrast to the 713 child frames used by Corfu. Overall both packages work well, but 714 Company integrates less tightly with Emacs. The 715 ‘completion-styles’ support is more limited and the 716 ‘completion-at-point’ command and the ‘completion-in-region’ 717 function do not invoke Company. 718 719 • consult-completion-in-region (https://github.com/minad/consult): 720 The Consult package provides the function 721 ‘consult-completion-in-region’ which can be set as 722 ‘completion-in-region-function’ such that it handles 723 ‘completion-at-point’. The function works by transferring the 724 in-buffer completion to the minibuffer. In the minibuffer, the 725 minibuffer completion UI, for example Vertico 726 (https://github.com/minad/vertico) takes over. If you prefer to 727 perform all your completions in the minibuffer 728 ‘consult-completion-in-region’ is your best option. 729 730 731 File: docxDqOT0.info, Node: Debugging Corfu, Next: Contributions, Prev: Alternatives, Up: Top 732 733 8 Debugging Corfu 734 ***************** 735 736 When you observe an error in the ‘corfu--post-command’ post command 737 hook, you should install an advice to enforce debugging. This allows 738 you to obtain a stack trace in order to narrow down the location of the 739 error. The reason is that post command hooks are automatically disabled 740 (and not debugged) by Emacs. Otherwise Emacs would become unusable, 741 given that the hooks are executed after every command. 742 743 (setq debug-on-error t) 744 745 (defun force-debug (func &rest args) 746 (condition-case e 747 (apply func args) 748 ((debug error) (signal (car e) (cdr e))))) 749 750 (advice-add #'corfu--post-command :around #'force-debug) 751 752 When Capfs do not yield the expected result you can use 753 ‘cape-capf-debug’ to add debug messages to a Capf. The Capf will then 754 produce a completion log in the messages buffer. 755 756 (setq completion-at-point-functions (list (cape-capf-debug #'cape-dict))) 757 758 759 File: docxDqOT0.info, Node: Contributions, Prev: Debugging Corfu, Up: Top 760 761 9 Contributions 762 *************** 763 764 Since this package is part of GNU ELPA 765 (https://elpa.gnu.org/packages/corfu.html) contributions require a 766 copyright assignment to the FSF. 767 768 769 770 Tag Table: 771 Node: Top208 772 Node: Features2308 773 Node: Installation3769 774 Node: Key bindings4284 775 Node: Configuration5623 776 Node: Auto completion11389 777 Node: Completing in the minibuffer13912 778 Node: Completing in the Eshell or Shell16114 779 Node: Orderless completion19072 780 Node: TAB-only completion22149 781 Node: TAB-and-Go completion23680 782 Node: Expanding to the common candidate prefix with TAB24786 783 Node: Transfer completion to the minibuffer26201 784 Node: Extensions27654 785 Node: Complementary packages29455 786 Node: Alternatives31685 787 Node: Debugging Corfu33431 788 Node: Contributions34487 789 790 End Tag Table 791 792 793 Local Variables: 794 coding: utf-8 795 End: