diff --git a/etc/NEWS b/etc/NEWS index a59a1a3017d..ae267c4c5dd 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -184,6 +184,17 @@ accepts a comma-separated list. The prompt format can include the separator description and the separator string, which are both stored as text properties of the 'crm-separator' regular expression. +--- +*** New user option 'completion-preview-sort-function'. +This option controls how Completion Preview mode sorts completion +candidates. If you use this mode together with an in-buffer completion +popup interface, such as the interfaces that the GNU ELPA packages Corfu +and Company provide, you can set this option to the same sort function +that your popup interface uses for a more integrated experience. + +Note: 'completion-preview-sort-function' was present also in Emacs 30.1, +albeit as a variable, not a user option. + ** Windows +++ diff --git a/lisp/completion-preview.el b/lisp/completion-preview.el index 4fc9bb0c9f3..6ccf235dbc5 100644 --- a/lisp/completion-preview.el +++ b/lisp/completion-preview.el @@ -226,8 +226,20 @@ affect the background color, for example with `hl-line-mode'." (const :tag "Disable" nil)) :version "31.1") -(defvar completion-preview-sort-function #'minibuffer--sort-by-length-alpha - "Sort function to use for choosing a completion candidate to preview.") +(defcustom completion-preview-sort-function #'minibuffer--sort-by-length-alpha + "Sort function to use for choosing a completion candidate to preview. + +Completion Preview mode calls the function that this option specifies to +sort completion candidates. The function takes one argument, the list +of candidates, and returns the list sorted. + +The default sort function sorts first by length, then alphabetically. +To disable sorting, set this option to `identity'. + +If the completion table that produces the candidates already specifies a +sort function, it takes precedence over this option." + :type 'function + :version "31.1") (defface completion-preview '((t :inherit shadow))