[elpa] externals/corfu 8344352ef9: README: Document TAB-only configuration

[ELPA Syncer]

branch: externals/corfu
commit 8344352ef93077137e49729a4b0421b12fba79ae
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    README: Document TAB-only configuration
---
 README.org | 343 ++++++++++++++++++++++++++++++++++---------------------------
 1 file changed, 190 insertions(+), 153 deletions(-)

diff --git a/README.org b/README.org
index ae1a29e1f2..add4b659e6 100644
--- a/README.org
+++ b/README.org
@@ -80,44 +80,44 @@ set ~corfu-auto~ to t before turning on ~global-corfu-mode~.
 Here is an example configuration:
 
 #+begin_src emacs-lisp
-  (use-package corfu
-    ;; Optional customizations
-    ;; :custom
-    ;; (corfu-cycle t)                ;; Enable cycling for 
`corfu-next/previous'
-    ;; (corfu-auto t)                 ;; Enable auto completion
-    ;; (corfu-separator ?\s)          ;; Orderless field separator
-    ;; (corfu-quit-at-boundary nil)   ;; Never quit at completion boundary
-    ;; (corfu-quit-no-match nil)      ;; Never quit, even if there is no match
-    ;; (corfu-preview-current nil)    ;; Disable current candidate preview
-    ;; (corfu-preselect 'prompt)      ;; Preselect the prompt
-    ;; (corfu-on-exact-match nil)     ;; Configure handling of exact matches
-    ;; (corfu-scroll-margin 5)        ;; Use scroll margin
-
-    ;; Enable Corfu only for certain modes.
-    ;; :hook ((prog-mode . corfu-mode)
-    ;;        (shell-mode . corfu-mode)
-    ;;        (eshell-mode . corfu-mode))
-
-    ;; Recommended: Enable Corfu globally.
-    ;; This is recommended since Dabbrev can be used globally (M-/).
-    ;; See also `corfu-exclude-modes'.
-    :init
-    (global-corfu-mode))
-
-  ;; A few more useful configurations...
-  (use-package emacs
-    :init
-    ;; TAB cycle if there are only few candidates
-    (setq completion-cycle-threshold 3)
-
-    ;; Emacs 28: Hide commands in M-x which do not apply to the current mode.
-    ;; Corfu commands are hidden, since they are not supposed to be used via 
M-x.
-    ;; (setq read-extended-command-predicate
-    ;;       #'command-completion-default-include-p)
-
-    ;; Enable indentation+completion using the TAB key.
-    ;; `completion-at-point' is often bound to M-TAB.
-    (setq tab-always-indent 'complete))
+(use-package corfu
+  ;; Optional customizations
+  ;; :custom
+  ;; (corfu-cycle t)                ;; Enable cycling for `corfu-next/previous'
+  ;; (corfu-auto t)                 ;; Enable auto completion
+  ;; (corfu-separator ?\s)          ;; Orderless field separator
+  ;; (corfu-quit-at-boundary nil)   ;; Never quit at completion boundary
+  ;; (corfu-quit-no-match nil)      ;; Never quit, even if there is no match
+  ;; (corfu-preview-current nil)    ;; Disable current candidate preview
+  ;; (corfu-preselect 'prompt)      ;; Preselect the prompt
+  ;; (corfu-on-exact-match nil)     ;; Configure handling of exact matches
+  ;; (corfu-scroll-margin 5)        ;; Use scroll margin
+
+  ;; Enable Corfu only for certain modes.
+  ;; :hook ((prog-mode . corfu-mode)
+  ;;        (shell-mode . corfu-mode)
+  ;;        (eshell-mode . corfu-mode))
+
+  ;; Recommended: Enable Corfu globally.
+  ;; This is recommended since Dabbrev can be used globally (M-/).
+  ;; See also `corfu-exclude-modes'.
+  :init
+  (global-corfu-mode))
+
+;; A few more useful configurations...
+(use-package emacs
+  :init
+  ;; TAB cycle if there are only few candidates
+  (setq completion-cycle-threshold 3)
+
+  ;; Emacs 28: Hide commands in M-x which do not apply to the current mode.
+  ;; Corfu commands are hidden, since they are not supposed to be used via M-x.
+  ;; (setq read-extended-command-predicate
+  ;;       #'command-completion-default-include-p)
+
+  ;; Enable indentation+completion using the TAB key.
+  ;; `completion-at-point' is often bound to M-TAB.
+  (setq tab-always-indent 'complete))
 #+end_src
 
 Dabbrev completion is based on =completion-in-region= and can be used with 
Corfu.
@@ -126,14 +126,14 @@ easier access, if you prefer completion. Also take a look 
at the =cape-dabbrev=
 completion at point function provided by my 
[[https://github.com/minad/cape][Cape]] package.
 
 #+begin_src emacs-lisp
-  ;; Use Dabbrev with Corfu!
-  (use-package dabbrev
-    ;; Swap M-/ and C-M-/
-    :bind (("M-/" . dabbrev-completion)
-           ("C-M-/" . dabbrev-expand))
-    ;; Other useful Dabbrev configurations.
-    :custom
-    (dabbrev-ignored-buffer-regexps '("\\.\\(?:pdf\\|jpe?g\\|png\\)\\'")))
+;; Use Dabbrev with Corfu!
+(use-package dabbrev
+  ;; Swap M-/ and C-M-/
+  :bind (("M-/" . dabbrev-completion)
+         ("C-M-/" . dabbrev-expand))
+  ;; Other useful Dabbrev configurations.
+  :custom
+  (dabbrev-ignored-buffer-regexps '("\\.\\(?:pdf\\|jpe?g\\|png\\)\\'")))
 #+end_src
 
 If you start to configure the package more deeply, I recommend to give the
@@ -142,15 +142,15 @@ different from the familiar prefix TAB completion. Corfu 
can be used with the
 default completion styles. The use of Orderless is not a necessity.
 
 #+begin_src emacs-lisp
-  ;; Optionally use the `orderless' completion style.
-  (use-package orderless
-    :init
-    ;; Configure a custom style dispatcher (see the Consult wiki)
-    ;; (setq orderless-style-dispatchers '(+orderless-dispatch)
-    ;;       orderless-component-separator 
#'orderless-escapable-split-on-space)
-    (setq completion-styles '(orderless basic)
-          completion-category-defaults nil
-          completion-category-overrides '((file (styles . 
(partial-completion))))))
+;; Optionally use the `orderless' completion style.
+(use-package orderless
+  :init
+  ;; Configure a custom style dispatcher (see the Consult wiki)
+  ;; (setq orderless-style-dispatchers '(+orderless-dispatch)
+  ;;       orderless-component-separator #'orderless-escapable-split-on-space)
+  (setq completion-styles '(orderless basic)
+        completion-category-defaults nil
+        completion-category-overrides '((file (styles . 
(partial-completion))))))
 #+end_src
 
 The =basic= completion style is specified as fallback in addition to 
=orderless= in
@@ -176,9 +176,9 @@ such that the completion popup stays out of your way when 
it appeared
 unexpectedly.
 
 #+begin_src emacs-lisp
-  ;; Enable auto completion and configure quitting
-  (setq corfu-auto t
-        corfu-quit-no-match 'separator) ;; or t
+;; Enable auto completion and configure quitting
+(setq corfu-auto t
+      corfu-quit-no-match 'separator) ;; or t
 #+end_src
 
 I recommend to experiment a bit with the various settings and key bindings to
@@ -193,33 +193,33 @@ very fast in buffers with efficient completion backends. 
You can try the
 following settings in an Elisp buffer or the Emacs scratch buffer.
 
 #+begin_src emacs-lisp
-  ;; Aggressive completion, cheap prefix filtering.
-  (setq-local corfu-auto t
-              corfu-auto-delay 0
-              corfu-auto-prefix 0
-              completion-styles '(basic))
+;; Aggressive completion, cheap prefix filtering.
+(setq-local corfu-auto t
+            corfu-auto-delay 0
+            corfu-auto-prefix 0
+            completion-styles '(basic))
 #+end_src
 
 If you want to combine fast prefix filtering and Orderless filtering you can
 still do that by defining a custom Orderless completion style via
 =orderless-define-completion-style=. We use a custom style dispatcher, which
-enables prefix filtering for input shorter than 4 characters. Note that such a
-setup is quite advanced. Please refer to the Orderless documentation and source
-code for further details.
+enables efficient prefix filtering for input shorter than 4 characters. Note
+that such a setup is advanced. Please refer to the Orderless documentation and
+source code for further details.
 
 #+begin_src emacs-lisp
-  (defun orderless-fast-dispatch (word index total)
-    (and (= index 0) (= total 1) (length< word 4)
-         `(orderless-regexp . ,(concat "^" (regexp-quote word)))))
-
-  (orderless-define-completion-style orderless-fast
-    (orderless-style-dispatchers '(orderless-fast-dispatch))
-    (orderless-matching-styles '(orderless-literal orderless-regexp)))
-
-  (setq-local corfu-auto t
-              corfu-auto-delay 0
-              corfu-auto-prefix 0
-              completion-styles '(orderless-fast))
+(defun orderless-fast-dispatch (word index total)
+  (and (= index 0) (= total 1) (length< word 4)
+       `(orderless-regexp . ,(concat "^" (regexp-quote word)))))
+
+(orderless-define-completion-style orderless-fast
+  (orderless-style-dispatchers '(orderless-fast-dispatch))
+  (orderless-matching-styles '(orderless-literal orderless-regexp)))
+
+(setq-local corfu-auto t
+            corfu-auto-delay 0
+            corfu-auto-prefix 1
+            completion-styles '(orderless-fast basic))
 #+end_src
 
 ** Completing in the minibuffer
@@ -234,14 +234,14 @@ enable Corfu completion for commands like ~M-:~ 
(~eval-expression~) or ~M-!~
 effect.
 
 #+begin_src emacs-lisp
-    (defun corfu-enable-in-minibuffer ()
-      "Enable Corfu in the minibuffer if `completion-at-point' is bound."
-      (when (where-is-internal #'completion-at-point (list 
(current-local-map)))
-        ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
-        (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
-                    corfu-popupinfo-delay nil)
-        (corfu-mode 1)))
-    (add-hook 'minibuffer-setup-hook #'corfu-enable-in-minibuffer)
+(defun corfu-enable-in-minibuffer ()
+  "Enable Corfu in the minibuffer if `completion-at-point' is bound."
+  (when (where-is-internal #'completion-at-point (list (current-local-map)))
+    ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
+    (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
+                corfu-popupinfo-delay nil)
+    (corfu-mode 1)))
+(add-hook 'minibuffer-setup-hook #'corfu-enable-in-minibuffer)
 #+end_src
 
 You can also enable Corfu more generally for every minibuffer, as long as no
@@ -250,16 +250,16 @@ Furthermore we ensure that Corfu is not enabled if a 
password is read from the
 minibuffer.
 
 #+begin_src emacs-lisp
-  (defun corfu-enable-always-in-minibuffer ()
-    "Enable Corfu in the minibuffer if Vertico/Mct are not active."
-    (unless (or (bound-and-true-p mct--active)
-                (bound-and-true-p vertico--input)
-                (eq (current-local-map) read-passwd-map))
-      ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
-      (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
-                  corfu-popupinfo-delay nil)
-      (corfu-mode 1)))
-  (add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)
+(defun corfu-enable-always-in-minibuffer ()
+  "Enable Corfu in the minibuffer if Vertico/Mct are not active."
+  (unless (or (bound-and-true-p mct--active)
+              (bound-and-true-p vertico--input)
+              (eq (current-local-map) read-passwd-map))
+    ;; (setq-local corfu-auto nil) ;; Enable/disable auto completion
+    (setq-local corfu-echo-delay nil ;; Disable automatic echo and popup
+                corfu-popupinfo-delay nil)
+    (corfu-mode 1)))
+(add-hook 'minibuffer-setup-hook #'corfu-enable-always-in-minibuffer 1)
 #+end_src
 
 ** Completing in the Eshell or Shell
@@ -269,10 +269,10 @@ auto completion, such that the completion behavior is 
similar to widely used
 shells like Bash, Zsh or Fish.
 
 #+begin_src emacs-lisp
-  (add-hook 'eshell-mode-hook
-            (lambda ()
-              (setq-local corfu-auto nil)
-              (corfu-mode)))
+(add-hook 'eshell-mode-hook
+          (lambda ()
+            (setq-local corfu-auto nil)
+            (corfu-mode)))
 #+end_src
 
 When pressing =RET= while the Corfu popup is visible, the ~corfu-insert~ 
command
@@ -283,15 +283,15 @@ confirmation. Fortunately it is easy to improve this! In 
my configuration I
 define the advice ~corfu-send-shell~ which sends the candidate after insertion.
 
 #+begin_src emacs-lisp
-  (defun corfu-send-shell (&rest _)
-    "Send completion candidate when inside comint/eshell."
-    (cond
-     ((and (derived-mode-p 'eshell-mode) (fboundp 'eshell-send-input))
-      (eshell-send-input))
-     ((and (derived-mode-p 'comint-mode)  (fboundp 'comint-send-input))
-      (comint-send-input))))
-
-  (advice-add #'corfu-insert :after #'corfu-send-shell)
+(defun corfu-send-shell (&rest _)
+  "Send completion candidate when inside comint/eshell."
+  (cond
+   ((and (derived-mode-p 'eshell-mode) (fboundp 'eshell-send-input))
+    (eshell-send-input))
+   ((and (derived-mode-p 'comint-mode)  (fboundp 'comint-send-input))
+    (comint-send-input))))
+
+(advice-add #'corfu-insert :after #'corfu-send-shell)
 #+end_src
 
 Shell completion uses the flexible Pcomplete mechanism internally, which allows
@@ -317,14 +317,14 @@ advices on Emacs 29 and eventually report any remaining 
Pcomplete issues
 upstream, such that they can be fixed at the root.
 
 #+begin_src emacs-lisp
-  ;; The advices are only needed on Emacs 28 and older.
-  (when (< emacs-major-version 29)
-    ;; Silence the pcomplete capf, no errors or messages!
-    (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
-
-    ;; Ensure that pcomplete does not write to the buffer
-    ;; and behaves as a pure `completion-at-point-function'.
-    (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify))
+;; The advices are only needed on Emacs 28 and older.
+(when (< emacs-major-version 29)
+  ;; Silence the pcomplete capf, no errors or messages!
+  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
+
+  ;; Ensure that pcomplete does not write to the buffer
+  ;; and behaves as a pure `completion-at-point-function'.
+  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify))
 #+end_src
 
 ** Orderless completion
@@ -365,26 +365,63 @@ completion and one which may work better with manual 
completion if you prefer to
 always use =SPC= to separate the Orderless components.
 
  #+begin_src emacs-lisp
-   ;; Auto completion example
-   (use-package corfu
-     :custom
-     (corfu-auto t)          ;; Enable auto completion
-     ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
-     :bind
-     ;; Another key binding can be used, such as S-SPC.
-     ;; (:map corfu-map ("M-SPC" . corfu-insert-separator))
-     :init
-     (global-corfu-mode))
-
-   ;; Manual completion example
-   (use-package corfu
-     :custom
-     ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
-     :bind
-     ;; Configure SPC for separator insertion
-     (:map corfu-map ("SPC" . corfu-insert-separator))
-     :init
-     (global-corfu-mode))
+ ;; Auto completion example
+ (use-package corfu
+   :custom
+   (corfu-auto t)          ;; Enable auto completion
+   ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
+   :bind
+   ;; Another key binding can be used, such as S-SPC.
+   ;; (:map corfu-map ("M-SPC" . corfu-insert-separator))
+   :init
+   (global-corfu-mode))
+
+ ;; Manual completion example
+ (use-package corfu
+   :custom
+   ;; (corfu-separator ?_) ;; Set to orderless separator, if not using space
+   :bind
+   ;; Configure SPC for separator insertion
+   (:map corfu-map ("SPC" . corfu-insert-separator))
+   :init
+   (global-corfu-mode))
+#+end_src
+
+** TAB-only completion
+
+By default, Corfu steals both the ~RET~ and ~TAB~ keys, when the Corfu popup is
+open. This can feel intrusive, in particular in combination with auto
+completion. ~RET~ may accidentally commit an automatically selected candidate,
+while you actually wanted to start a new line. As an alternative we can unbind
+the ~RET~ key completely from ~corfu-map~ or reserve the ~RET~ key only in 
shell
+modes.
+
+#+begin_src emacs-lisp
+;; TAB-only configuration
+(use-package corfu
+  :custom
+  (corfu-auto t)               ;; Enable auto completion
+  (corfu-preselect 'directory) ;; Select the first candidate, except for 
directories
+
+  ;; Free the RET key for less intrusive behavior.
+  :bind
+  (:map corfu-map
+        ;; Option 1: Unbind RET completely
+        ;;; ("RET" . nil)
+        ;; Option 2: Use RET only in shell modes
+        ("RET" . (menu-item "" nil :filter corfu-insert-shell-filter)))
+
+  :init
+  (global-corfu-mode))
+
+(defun corfu-insert-shell-filter (&optional _)
+  "Insert completion candidate and send when inside comint/eshell."
+  (when (derived-mode-p 'eshell-mode 'comint-mode)
+    (lambda ()
+      (interactive)
+      (corfu-insert)
+      ;; `corfu-send-shell' was defined above
+      (corfu-send-shell))))
 #+end_src
 
 ** TAB-and-Go completion
@@ -396,22 +433,22 @@ desired but which leads overall to a more predictable 
behavior. In order to
 force snippet expansion, confirm a candidate explicitly with ~RET~.
 
 #+begin_src emacs-lisp
-  (use-package corfu
-    ;; TAB-and-Go customizations
-    :custom
-    (corfu-cycle t)           ;; Enable cycling for `corfu-next/previous'
-    (corfu-preselect 'prompt) ;; Always preselect the prompt
-
-    ;; Use TAB for cycling, default is `corfu-complete'.
-    :bind
-    (:map corfu-map
-          ("TAB" . corfu-next)
-          ([tab] . corfu-next)
-          ("S-TAB" . corfu-previous)
-          ([backtab] . corfu-previous))
-
-    :init
-    (global-corfu-mode))
+(use-package corfu
+  ;; TAB-and-Go customizations
+  :custom
+  (corfu-cycle t)           ;; Enable cycling for `corfu-next/previous'
+  (corfu-preselect 'prompt) ;; Always preselect the prompt
+
+  ;; Use TAB for cycling, default is `corfu-complete'.
+  :bind
+  (:map corfu-map
+        ("TAB" . corfu-next)
+        ([tab] . corfu-next)
+        ("S-TAB" . corfu-previous)
+        ([backtab] . corfu-previous))
+
+  :init
+  (global-corfu-mode))
 #+end_src
 
 ** Transfer completion to the minibuffer