Add Capf transformer examples

1 files changed, 42 insertions, 2 deletions

diff --git a/README.org b/README.org
index ffbbd4d..3261b1a 100644
--- a/README.org
+++ b/README.org
@@ -102,7 +102,6 @@ could be upstreamed into Emacs itself.
 #+end_src
 
 * Experimental features
-
 ** Company adapter
 
 /Wrap your Company backend in a Cape and turn it into a Capf!/
@@ -219,6 +218,11 @@ achieve a similarly refreshing strategy.
 
 ** Other Capf transformers
 
+Cape provides a set of additional Capf transformation functions, which are
+mostly meant to used by experts to fine tune the Capf behavior and Capf
+interaction. These can either be used as advices (=cape-wrap-*)= or to create a
+new Capf from an existing Capf (=cape-capf-*=).
+
 - ~cape-interactive-capf~: Create a Capf which can be called interactively.
 - ~cape-wrap-accept-all~, ~cape-capf-accept-all~: Create a Capf which accepts every input as valid.
 - ~cape-wrap-silent~, ~cape-capf-silent~: Wrap a chatty Capf and silence it.
@@ -227,7 +231,43 @@ achieve a similarly refreshing strategy.
 - ~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.
-- ~cape-wrap-prefix-length~, ~cape-capf-prefix-length~: Enforce a minimal prefix length.
+- ~cape-wrap-prefix-length~, ~cape-capf-prefix-length~: Enforce a minimal prefix
+  length.
+
+In the following we show a few example configurations, which have come up on the
+[[https://github.com/minad/cape/issues][Cape]] or [[https://github.com/minad/corfu/issues][Corfu issue tracker]] or the [[https://github.com/minad/corfu/wiki][Corfu wiki.]] I use some of these tweaks in my
+personal configuration.
+
+#+begin_src emacs-lisp
+  ;; Example 1: Sanitize the `pcomplete-completions-at-point' Capf.
+  ;; The Capf has undesired side effects on Emacs 28 and earlier.
+  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-silent)
+  (advice-add 'pcomplete-completions-at-point :around #'cape-wrap-purify)
+
+  ;; Example 2: Configure a Capf with a specific auto completion prefix length
+  (setq-local completion-at-point-functions
+              (list (cape-capf-prefix-length #'cape-dabbrev 2)))
+
+  ;; Example 3: Define a defensive Dabbrev Capf, which accepts all inputs.
+  ;; If you use Corfu and `corfu-auto=t', the first candidate won't be auto
+  ;; selected! You can use this instead of `cape-dabbrev'.
+  (defun my-cape-dabbrev-accept-all ()
+    (cape-wrap-accept-all #'cape-dabbrev))
+  (add-to-list 'completion-at-point-functions #'my-cape-dabbrev-accept-all)
+
+  ;; Example 4: Define interactive Capf which can be bound to a key.
+  ;; Here we wrap the `elisp-completion-at-point' such that we can
+  ;; complete Elisp code explicitly in arbitrary buffers.
+  (global-set-key (kbd "C-c p e")
+                  (cape-interactive-capf #'elisp-completion-at-point))
+
+  ;; Example 5: Ignore :keywords in Elisp completion.
+  (defun ignore-elisp-keywords (sym)
+    (not (keywordp sym)))
+  (setq-local completion-at-point-functions
+              (list (cape-capf-predicate #'elisp-completion-at-point
+                                         #'ignore-elisp-keywords)))
+#+end_src
 
 * Contributions