Introduce cider-enable-flex-completion (#3509)

Replaces `cider-company-enable-fuzzy-completion`, which is now deprecated.

Author: vemv

CHANGELOG.md

@@ -50,6 +50,7 @@
 
 - Ensure that `cider` completion isn't used with completion styles that are currently unsupported (`initials`, `partial-completion`, `orderless`, etc).
   - This restores completions for users that favor those styles - otherwise the would see bad or no completions.
+  - Relatedly, `cider-company-enable-fuzzy-completion` is now deprecated in favor of `cider-enable-flex-completion`.
 - Improve support for multiple forms in the same line by replacing `beginning-of-defun` fn.
 - [#3390](https://github.com/clojure-emacs/cider/issues/3390): Enhance `cider-connect` to show all nREPLs available ports, instead of only Leiningen ones.
 - [#3408](https://github.com/clojure-emacs/cider/issues/3408): `cider-connect`: check `.nrepl-port`-like files for liveness, hiding them if they don't reflect an active port.

cider-completion.el

@@ -36,6 +36,7 @@
 (require 'cider-docstring)
 (require 'cider-eldoc)
 (require 'nrepl-dict)
+(require 'seq)
 
 (defcustom cider-annotate-completion-candidates t
   "When true, annotate completion candidates with some extra information."
@@ -193,7 +194,7 @@ performed by `cider-annotate-completion-function'."
               ;;
               ;; This api is better described in the section
               ;; '21.6.7 Programmed Completion' of the elisp manual.
-              (cond ((eq action 'metadata) `(metadata (category . cider)))
+              (cond ((eq action 'metadata) `(metadata (category . cider))) ;; defines a completion category named 'cider, used later in our `completion-category-overrides` logic.
                     ((eq (car-safe action) 'boundaries) nil)
                     (t (with-current-buffer (current-buffer)
                          (complete-with-action action
@@ -243,6 +244,12 @@ in the buffer."
   "Return CIDER completion candidates for STRING as is, unfiltered."
   (cider-complete string))
 
+;; defines a completion style named `cider' (which ideally would have been named `cider-fuzzy').
+;; note that there's already a completion category named `cider' (grep for `(metadata (category . cider))` in this file),
+;; which can be confusing given the identical name.
+;; The `cider' completion style should be removed because the `flex' style is essentially equivalent.
+;; (To be fair, `flex' was introduced in Emacs 27, 3 years in after our commit 04e428b
+;;  which introduced `cider-company-enable-fuzzy-completion')
 (add-to-list 'completion-styles-alist
              '(cider
                cider-company-unfiltered-candidates
@@ -252,11 +259,35 @@ in the buffer."
 ;; Currently CIDER completions only work for `basic`, and not `initials`, `partial-completion`, `orderless`, etc.
 ;; So we ensure that those other styles aren't used with CIDER, otherwise one would see bad or no completions at all.
 ;; This `add-to-list` call can be removed once we implement the other completion styles.
-(add-to-list 'completion-category-overrides '(cider (styles basic flex)))
+;; (When doing that, please refactor `cider-enable-flex-completion' as well)
+(add-to-list 'completion-category-overrides '(cider (styles basic)))
 
 (defun cider-company-enable-fuzzy-completion ()
-  "Enable backend-driven fuzzy completion in the current buffer."
+  "Enable backend-driven fuzzy completion in the current buffer.
+
+DEPRECATED: please use `cider-enable-flex-completion' instead."
   (setq-local completion-styles '(cider)))
 
+(make-obsolete 'cider-company-enable-fuzzy-completion 'cider-enable-flex-completion "1.8.0")
+
+(defun cider-enable-flex-completion ()
+  "Enables `flex' (fuzzy) completion for CIDER in all buffers.
+
+Only affects the `cider' completion category.`"
+  (interactive)
+  (when (< emacs-major-version 27)
+    (user-error "`cider-enable-flex-completion' requires Emacs 27 or later"))
+  (let ((found-styles (when-let ((cider (assq 'cider completion-category-overrides)))
+                        (assq 'styles cider)))
+        (found-cycle (when-let ((cider (assq 'cider completion-category-overrides)))
+                       (assq 'cycle cider))))
+    (setq completion-category-overrides (seq-remove (lambda (x)
+                                                      (equal 'cider (car x)))
+                                                    completion-category-overrides))
+    (unless (member 'flex found-styles)
+      (setq found-styles (append found-styles '(flex))))
+    (add-to-list 'completion-category-overrides (apply #'list 'cider found-styles (when found-cycle
+                                                                                    (list found-cycle))))))
+
 (provide 'cider-completion)
 ;;; cider-completion.el ends here

doc/modules/ROOT/pages/usage/code_completion.adoc

@@ -39,16 +39,17 @@ is already properly indented.
 
 CIDER defines (via the `completion-styles-alist` Elisp variable) a completion category named `cider`.
 
-The `cider` completion category currently only supports `basic` and `flex` completion styles (and not `partial-completion`, `orderless`, etc).
+The `cider` completion category currently only supports `basic` completion styles (and not `partial-completion`, `orderless`, etc),
+and `flex`, optionally (read more below).
 
 CIDER declares so in this fashion:
 
 [source,lisp]
 ----
-(add-to-list 'completion-category-overrides '(cider (styles basic flex)))
+(add-to-list 'completion-category-overrides '(cider (styles basic)))
 ----
 
-Note that `flex` will only work if you also enabled xref:usage/code_completion.adoc#fuzzy-candidate-matching[fuzzy candidate matching].
+You can also enable the `flex` completion style by activating xref:usage/code_completion.adoc#fuzzy-candidate-matching[fuzzy candidate matching].
 
 == Auto-completion
 
@@ -130,27 +131,30 @@ without needing to hit an extra key, please customize:
 
 === Fuzzy candidate matching
 
-By default `company-mode` will provide completion candidates with the
+By default, CIDER will provide completion candidates with the
 assumption that whatever you've typed so far is a prefix of what
 you're really trying to type. For example, if you type `map-` then
 you'll only get completion candidates that have `map-` as the
 beginning of their names.  Sometimes, you don't know the exact prefix
 for the item you want to type. In this case, you can get
-CIDER-specific "fuzzy completion" by adding:
+CIDER-specific "fuzzy completion" by setting up in your Emacs init file:
 
 [source,lisp]
 ----
-(add-hook 'cider-repl-mode-hook #'cider-company-enable-fuzzy-completion)
-(add-hook 'cider-mode-hook #'cider-company-enable-fuzzy-completion)
+(cider-enable-flex-completion)
 ----
 
+This adds the `flex` completion style, as introduced in Emacs 27.
+
 Now, `company-mode` will accept certain fuzziness when matching
 candidates against the prefix. For example, typing `mi` will show you
 `map-indexed` as one of the possible completion candidates and `cji`
 will complete to `clojure.java.io`. Different completion examples are
 shown
 https://github.com/alexander-yakushev/compliment/wiki/Examples[here].
 
+NOTE: `cider-company-enable-fuzzy-completion` (now deprecated) should be used for Emacs < 27. 
+
 === Completion annotations
 
 Completion candidates will be annotated by default with an abbreviation

test/cider-completion-tests.el

@@ -0,0 +1,55 @@
+;;; cider-completion-tests.el  -*- lexical-binding: t; -*-
+
+;; Copyright © 2012-2023 Bozhidar Batsov
+
+;; Author: Bozhidar Batsov <[email protected]>
+
+;; This file is NOT part of GNU Emacs.
+
+;; This program is free software: you can redistribute it and/or
+;; modify it under the terms of the GNU General Public License as
+;; published by the Free Software Foundation, either version 3 of the
+;; License, or (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful, but
+;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;; General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see `http://www.gnu.org/licenses/'.
+
+;;; Commentary:
+
+;; This file is part of CIDER
+
+;;; Code:
+
+(require 'buttercup)
+(require 'cider-completion)
+
+;; Please, for each `describe', ensure there's an `it' block, so that its execution is visible in CI.
+
+(describe "cider-enable-flex-completion"
+  (when (>= emacs-major-version 27)
+    (cl-assert (not (member 'flex (assq 'styles (assq 'cider completion-category-overrides)))))
+    (let ((old-value completion-category-overrides))
+      (unwind-protect
+          (progn
+            (it "adds `flex'"
+              (cider-enable-flex-completion)
+              (expect (member 'flex (assq 'styles (assq 'cider completion-category-overrides)))
+                      :to-be-truthy))
+
+            (it "doesn't add `cycle'"
+              (expect (assq 'cycle (assq 'cider completion-category-overrides))
+                      :to-be nil))
+
+            (it "doesn't re-add `flex' if already present, preserving `cycle' as well"
+              (let ((with-flex-and-cycle '((cider (styles basic flex)
+                                                  (cycle t)))))
+                (setq completion-category-overrides with-flex-and-cycle)
+                (cider-enable-flex-completion)
+                (expect completion-category-overrides
+                        :to-equal with-flex-and-cycle))))
+        (setq completion-category-overrides old-value)))))