Subject: 30.0.92; FR: Add a function completion-list-candidate-at-point

From: Daniel Mendler <[email-masked]>
Date: Sun, 17 Nov 2024 22:10:08 +0100

Emacs 31 comes with the internal function
`completions--start-of-candidate-at' in simple.el, which returns the
position of the completion candidate at point in the completions buffer.
I propose to replace this function with a slightly improved version,
which returns the candidate string in addition to the candidate bounds.
It could be made part of the public API:

(defun completion-list-candidate-at-point ()
  "Return completion candidate string at point with bounds in completions buffer."
  (let (beg end)
    (when (cond
           ((and (not (eobp)) (get-text-property (point) 'completion--string))
            (setq end (point) beg (1+ (point))))
           ((and (not (bobp)) (get-text-property (1- (point)) 'completion--string))
            (setq end (1- (point)) beg (point))))
      (list (get-text-property
             (previous-single-property-change beg 'completion--string)
             'completion--string)
            beg end))))

For a few years, the GNU ELPA packages like Embark and Consult had
versions of this function. These packages need to obtain the completion
candidate at point when acting on the candidate. If
`completion-list-candidate-at-point' is made available in Emacs, I can
port it back via the GNU ELPA Compat package, such that external
packages can take advantage of the new function, and don't have to rely
on internals like the `completion--string' property.

If there is interest, I can provide a patch for simple.el which replaces
`completions--start-of-candidate-at'. Thank you for your consideration.

Daniel