Selectrum 3.0

Breaking changes

• The function selectrum-read-directory-name is no longer available.
• When reading directories and the default is already in the prompt, it gets selected so you can immediately submit it (#126, #127). In correspondence with this change, the initial working directory for read-directory-name is now unchanged from the Emacs default, rather than being the parent directory.
• Selectrum now uses a keymap (selectrum-minibuffer-map) instead of an alist (selectrum-minibuffer-bindings, now removed) for configuring bindings (#186). This better meets users' expectations, and allows other packages (e.g., General) to better work with Selectrum's keybindings (#71).

Features

• The user option selectrum-completing-read-multiple-show-help can be used to control display of additional usage information in the prompt in a completing-read-multiple session (#130, #132).
• selectrum-read accepts two additional keyword arguments minibuffer-completion-table and minibuffer-completion-predicate. These can be used to pass the completing-read collection and predicate so they are available for internal handling of completion API features and for other external commands or packages which make use of them (#94, #95).
• If the completion table passed to completing-read provides annotation-function or display-sort-function in its metadata, Selectrum will use this information to annotate or sort the candidates accordingly. Annotations defined by completion-extra-properties are handled, too (#82, #95).
• One can trigger an update of Selectrum's completions UI manually by calling selectrum-exhibit (#95).
• You can now interact with candidates via the mouse. Left click (mouse-1) selects the candidate, and right click (mouse-3) inserts the candidate, just like RET and TAB, respectively. See #113 and #118.

Enhancements

• If selectrum-candidate-display-right-margin is used the margin is included in the highlighting of the selected candidate so it's easier to see to which candidate the margin belongs to (#166).
• If the default-filename passed to selectrum-read-file-name is an absolute path it will still be sorted to the top when it is contained in the prompting directory (#160).
• icomplete-mode is now automatically disabled when entering Selectrum, to avoid conflicts (#99).
• Working with the default candidate has been improved in cases where it is not in the candidate list. Such candidates are currently shown in the prompt message. For example, the command lgrep might suggest searching through files matching *.el instead of just a specific file. See #120, #122.
  • While there is no user input, the default candidate remains visible in the prompt message. Previously, it would be hidden when the prompt line was not selected. Unchanged is the behavior is to hide the default candidate when text is typed, so that it is only visible when it can be submitted (similar to the effect of minibuffer-electric-default-mode).
  • The default candidate shown in the prompt message is now displayed with the face selectrum-current-candidate when it is selected.
  • Now that Selectrum always shows the default candidate when it can be submitted, it now attempts to remove the default candidate from prompt messages that already contain it. This decreases redundancy.
• When there is no default value the prompt shows [default-value : ""] to indicate that you would submit the empty string. Previously it showed [default-value: none] (#133).
• When reading file names spaces are now considered symbol constituents which means you can use s-expression commands to navigate and edit the input more efficently. A binding for backward-kill-sexp was added to go up a directory with C-M-DEL (#138).
• Compliance to default minibuffer API has been further improved by using an overlay for candidates display. Previously code which assumed that the minibuffer only contains user input would be likely to fail (#124). This also means inside the minibuffer minibuffer-contents now returns only the current input as expected (#116, #133).
• Multiline candidates are now merged into a single truncated line so there is no gradual scrolling effect anymore when going through the candidate list. The first matched line is shown in front of the merged lines (#133). This formatting is customizable via selectrum-multiline-display-settings (#147).
• selectrum-insert-current-candidate now automatically inserts the separator for common values of crm-separator when using completing-read-multiple (#197).

Bugs fixed

• The minibuffer height is now determined by the actual height of displayed candidates. Previously the height could be off for candidates containing unicode characters or other means which changed the display height such as line-spacing (#146, #151, #154).
• When passing a named function or compiled lambda as CANDIDATES argument to selectrum-read an error would be thrown, which has been fixed (#163).
• When selecting file name prompts and submitting them the result will be the selected prompt. Previously it could be the default file name passed to selectrum-read-file-name which is the behavior of default completion where there is no concept of an active selection (#157, #160).
• When there are no candidates and a match isn't required the prompt will now be shown as selected to indicate one can submit the input (#160).
• If the MUSTMATCH argument to read-directory-name was non-nil the selection of the prompt wasn't visible which has been fixed (#157, #160).
• If a predicate was passed to read-buffer an error would be thrown which has been fixed (#159, #161).
• Dynamic collection functions can now reuse their returned candidates. Previously Selectrum could modify them even when the :may-modify-candidates argument wasn't passed to selectrum-read.
• Incremental history search via isearch wasn't working which has been fixed (#124, #133).
• Empty string completion candidates are now ignored like in the default completion UI (#101).
• Text properties are now stripped for standard completion functions (#107, #108).
• You can now select and submit empty input and for file prompts existing paths when require-match is non-nil (#67, #125).
• The default candidate is now first selected, even when it is not in the candidate list, conforming with expectations. Previously, the first candidate in the list was selected instead. See #120.
• selectrum-insert-current-candidate now works correctly for completing-read-multiple when crm-separator has a non default value. Previously it would replace the separator with commas when adding new candidates (#140).
• selectrum-insert-current-candidate now works from selectrum-select-from-history and other commands which ignore history by setting minibuffer-history-variable to t. Previously an error would be thrown (#152).
• When completing filenames and a match is required, non-normalized paths (e.g., ~/Documents//etc/hosts) are accepted (#190).
• Pressing TAB when nothing matches shows a “No match” message in the minibuffer instead of signaling an error and erasing the minibuffer contents (#193). If completion-fail-discreetly is non-nil, nothing is done.
• Fix type mismatch when configuring selectrum-count-style in customizations.
• Submitting the default value with the empty prompt does no longer strip the text properties of the default candidate (#180, #198).