branch: externals/cape
commit 98c375e6279c55c4e0c1a14df5ab8fbc0c8018d4
Author: Daniel Mendler <[email protected]>
Commit: Daniel Mendler <[email protected]>
Improve cape-capf-sort
---
CHANGELOG.org | 2 ++
README.org | 27 ++++++++++++++++++---------
cape.el | 2 +-
3 files changed, 21 insertions(+), 10 deletions(-)
diff --git a/CHANGELOG.org b/CHANGELOG.org
index e15f360005..830e3d83a3 100644
--- a/CHANGELOG.org
+++ b/CHANGELOG.org
@@ -5,6 +5,8 @@
* Development
- Mark ~cape-capf-purify~ and ~cape-wrap-purify~ as obsolete.
+- ~cape-capf-sort~: Make ~SORT~ function argument optional. If the ~SORT~
argument is
+ nil or not given, the completion UI sorting will take over.
* Version 2.2 (2025-10-13)
diff --git a/README.org b/README.org
index c5a16c6678..3652e3041c 100644
--- a/README.org
+++ b/README.org
@@ -176,12 +176,12 @@ with ~cape-capf-super~.
/Throw multiple Capfs under the Cape and get a Super-Capf!/
Cape supports merging multiple Capfs using the function ~cape-capf-super~. Due
to
-some technical details, not all Capfs can be merged successfully. Merge Capfs
+technical details, not all Capfs can be merged successfully. Try to merge Capfs
one by one and make sure that you get the desired outcome.
-Note that ~cape-capf-super~ is not needed if multiple Capfs should betried one
-after the other, for example you can use ~cape-file~ together with programming
-mode Capfs by adding ~cape-file~ to the ~completion-at-point-functions~ list.
File
+Note that ~cape-capf-super~ is not needed if multiple Capfs should be tried one
+after another, for example you can use ~cape-file~ together with programming
mode
+Capfs by adding ~cape-file~ to the ~completion-at-point-functions~ list. File
completion will then be available in comments and string literals, but not in
normal code. ~cape-capf-super~ is only necessary if you want to combine
multiple
Capfs, such that the candidates from multiple sources appear /together/ in the
@@ -194,15 +194,24 @@ and completion functions which do not define completion
boundaries.
static completion functions like ~cape-dabbrev~, ~cape-keyword~, ~cape-dict~,
etc.,
but not for multi-step completions like ~cape-file~.
+The results returned by the individual Capfs are listed after each other, where
+the the order of the completion candidates is preserved. In order to override
+this sorting behavior use ~cape-capf-sort~, such that the completion UI can
apply
+its own sorting.
+
#+begin_src emacs-lisp
;; Merge the dabbrev, dict and keyword capfs, display candidates together.
(setq-local completion-at-point-functions
- (list (cape-capf-super #'cape-dabbrev #'cape-dict #'cape-keyword)))
+ (list (cape-capf-super #'cape-dabbrev #'cape-dict)))
+
+;; Let the UI (e.g. Corfu) sort the candidates by overriding the sort function.
+(setq-local completion-at-point-functions
+ (list (cape-capf-sort (cape-capf-super #'cape-dabbrev
#'cape-dict))))
-;; Alternative: Define named Capf instead of using the anonymous Capf directly
-(defun cape-dabbrev-dict-keyword ()
- (cape-wrap-super #'cape-dabbrev #'cape-dict #'cape-keyword))
-(setq-local completion-at-point-functions (list #'cape-dabbrev-dict-keyword))
+;; Define named Capf instead of using the anonymous Capf directly.
+(defun cape-dabbrev-dict ()
+ (cape-wrap-super #'cape-dabbrev #'cape-dict))
+(setq-local completion-at-point-functions (list #'cape-dabbrev-dict))
#+end_src
See also the aforementioned ~company--multi-backend-adapter~ from Company,
which
diff --git a/cape.el b/cape.el
index f36915589c..4e8e150875 100644
--- a/cape.el
+++ b/cape.el
@@ -1110,7 +1110,7 @@ This function can be used as an advice around an existing
Capf."
(cape-wrap-properties capf :exclusive 'no))
;;;###autoload
-(defun cape-wrap-sort (capf sort)
+(defun cape-wrap-sort (capf &optional sort)
"Call CAPF and add SORT function.
This function can be used as an advice around an existing Capf."
(cape-wrap-properties
