external-completion.el: Minor changesscratch/backend-completion

* lisp/external-completion.el (external-completion-table): Tweak docstring.
Explicitly handle `lambda`.

* lisp/progmodes/eglot.el (xref-backend-identifier-completion-table):
Rename category to `eglot-xref`.

2 files changed, 43 insertions, 38 deletions

diff --git a/lisp/external-completion.el b/lisp/external-completion.el
index 4f5595e74bc..d305d3d923c 100644
--- a/lisp/external-completion.el
+++ b/lisp/external-completion.el
@@ -30,9 +30,9 @@
 ;; such as a shell utility, an inferior process, an http server.
 
 ;; The table and external tool are fully in control of the matching of
-;; the pattern string to the potential candidates of completion.  When
-;; `external' is in use, the usual styles configured by the user or
-;; other in `completion-styles' are ignored.
+;; the pattern string to the potential candidates of completion.
+;; When `external' is in use, the usual styles configured by the user
+;; or other in `completion-styles' are ignored.
 ;;
 ;; This compromise is for speed: all other styles need the full data
 ;; set to be available in Emacs' addressing space, which is often slow
@@ -50,13 +50,12 @@
                external-completion--all-completions
                "Ad-hoc completion style provided by the completion table."))
 
-(defun external-completion-table (category lookup
-                                           &optional metadata
-                                           try-completion-function)
+(defun external-completion-table ( category lookup
+                                   &optional metadata try-completion-function)
   "Make completion table using the `external' completion style.
 
 The completion table produced foregoes any styles normally set in
-`completion-styles' and will sets up an entry for the symbol
+`completion-styles' and will set up an entry for the symbol
 CATEGORY in `completion-category-defaults', linking it to the
 special completion style `external'.
 
@@ -65,43 +64,45 @@ tool that provides completions.  This may be a shell utility, an
 inferior process, an http server, etc.  The external tool does
 the matching, and the full set of candidates doesn't need to be
 transferred to Emacs's address space.  This often results in much
-faster overall completion at the expense of the convenience of
-offered by the rich variety of usual completion styles usually
-available.
+faster overall completion at the expense of the choice of
+completion styles.
 
-LOOKUP is a function taking a string PATTERN and a number
-POINT. The function should contact the backend and return a list
+LOOKUP is a function taking a string PATTERN and a position POINT.
+The function should contact the backend and return a list
 of strings representing the candidates matching PATTERN given
 that POINT is the location of point within it.  LOOKUP decides if
 PATTERN is interpreted as a substring, a regular expression, or
 any other type of matching key.  Strings returned by LOOKUP may
 be propertized with `completions-common-part' to illustrate the
-specific interpretationq.  To maintain responsiveness in the face
+specific interpretation.  To maintain responsiveness in the face
 of all but the spiffiest external tools, LOOKUP should detect
 timeouts and pending user input with `while-no-input' or
 `sit-for' (which see), cancel the request (if that is possible)
 and immediately return any non-list.
 
-CATEGORY is a symbol identifying the external tool.  METADATA is
-an alist of additional properties such as `cycle-sort-function'
+Calls to LOOKUP are cached.  There is no option to flush the cache,
+so if you need to do it, create a new completion table by calling
+`external-completion-table' again.
+
+
+CATEGORY is a symbol that should identify the kind of things
+being completed, so users can refer to it in `completion-category-override'.
+METADATA is an alist of additional properties such as `cycle-sort-function'
 to associate with CATEGORY.  This means that the caller may still
 retain control the sorting of the candidates while the tool
 controls the matching.
 
-TRY-COMPLETION-FUNCTION is if you want to get fancy.  It's a
-function taking a (PATTERN POINT ALL-COMPLETIONS), where PATTERN
+TRY-COMPLETION-FUNCTION is a function taking arguments
+\(PATTERN POINT ALL-COMPLETIONS), where PATTERN
 and POINT are as described above and ALL-COMPLETIONS are all
-candidates previously gathered by LOOKUP (don't worry, we do some
-caching so it doesn't get called more than needed).  If you know
-how the external tool is interpreting PATTERN,
-TRY-COMPLETION-FUNCTION may return a cons cell (NEW-PATTERN
-. NEW-POINT) to partially (or fully) complete the user's
-completion input.  For example, if the tool is completing by
-prefix, you could use `try-completion' to find the largest prefix
-in ALL-COMPLETIONS and then return that as NEW-PATTERN.  If the
-tool is using something else, like \"flex\", it's probably
-useless.  Anyway, the default is to return simply a (PATTERN
-. POINT) unaltered."
+candidates previously gathered by LOOKUP.  It should return
+a cons cell (NEWPATTERN . NEWPOINT) such that NEWPATTERN is
+as long as possible within the constraints that LOOKUP still returns
+the same set of candidates as it does for PATTERN and POINT.
+This can only be provided if you happen to know what kind of
+completion style is used by the external tool and is only worthwhile
+to provide if that completion style is fairly simple:
+if the tool is using something like \"flex\", it's probably useless."
   (unless (assq category completion-category-defaults)
     (push `(,category (styles external))
           completion-category-defaults))
@@ -130,17 +131,19 @@ useless.  Anyway, the default is to return simply a (PATTERN
              `(external-completion--allc
                . ,(if pred (cl-remove-if-not pred all) all))))
           (`(boundaries . ,_) nil)
+          ('lambda t) ;; `test-completion' should assume all results are valid.
           (_method
+           ;; FIXME: I suspect many external backends can't make much use of
+           ;; POINT, in which case the call below may actually be equivalent
+           ;; to one that's already in cache but we will fail to reuse it
+           ;; just because POINT is different :-(
            (let ((all (lookup-internal string (length string))))
              ;; This is here for two reasons:
              ;;
-             ;; * for when users try to work around
-             ;;   `completion-category-defaults' and access this table a
-             ;;   non-`external' completion style.  It won't work very
-             ;;   well, as this `all' here very often doesn't equate
-             ;;   "the full set" (many tools cap to sth like 100-1000
-             ;;   results).  FIXME: I think it would be better to just
-             ;;   error here.
+             ;; * for when users customize `completion-category-overrides'
+             ;;   to access this table with a non-`external' completion style.
+             ;;   It won't work very well for styles more complex than PCM,
+             ;;   but it should work fine for prefix completion.
              ;;
              ;; * for when `_method' above can also be `nil' or `lambda'
              ;;   which has some semantics and use I don't fully
@@ -160,10 +163,12 @@ useless.  Anyway, the default is to return simply a (PATTERN
         (cdr res)))))
 
 (defun external-completion--try-completion (string table pred point)
-  (external-completion--call 'external-completion--tryc string table pred point))
+  (external-completion--call 'external-completion--tryc
+                             string table pred point))
 
 (defun external-completion--all-completions (string table pred point)
-  (external-completion--call 'external-completion--allc string table pred point))
+  (external-completion--call 'external-completion--allc
+                             string table pred point))
 
 (provide 'external-completion)
 ;;; external-completion.el ends here
diff --git a/lisp/progmodes/eglot.el b/lisp/progmodes/eglot.el
index 5cc769d4b03..0dc7357a436 100644
--- a/lisp/progmodes/eglot.el
+++ b/lisp/progmodes/eglot.el
@@ -2575,7 +2575,7 @@ If BUFFER, switch to it before."
                             0 'eglot--lsp-workspaceSymbol c)
                            :score 0)))
       (external-completion-table
-       'eglot-indirection-joy
+       'eglot-xref
        #'lookup
        `((cycle-sort-function
           . ,(lambda (completions)