Selectrum 3.1

Deprecated

• The selectrum-read API has been deprecated and made private. The intention of this change is to encourage users instead to rely on the plain completing-read function, which is completion system agnostic ([#446]).
• The user option selectrum-fix-minibuffer-height has been deprecated. The new variable selectrum-fix-vertical-window-height takes its place ([#305]).
• The special text property selectrum-candidate-full to change the canonical representation of a candidate has been deprecated ([#403]).
• The hooks selectrum-candidate-inserted-hook and selectrum-candidate-selected-hook originally also received the arguments passed to selectrum-read which has been deprecated. These hooks are expected to be updated to only receive a single argument now, the inserted/selected candidate ([#446]).
• selectrum-default-candidate-refine-function and selectrum-default-candidate-highlight-function have been deprecated, see the new default values for selectrum-refine-candidates-function and selectrum-highlight-candidates-function which should be used instead ([#330]).

Changed defaults

• The default value of selectrum-num-candidates-displayed has changed to auto. If you have customized selectrum-num-candidates-displayed you should remove that from your configuration or also adjust it to auto. For configuring the window height you should use the new selectrum-max-window-height option now ([#305]).
• The new default functions used for selectrum-refine-candidates-function and selectrum-highlight-candidates-function have been updated to filter and highlight candidates according to completion-styles now ([#330]).

Features

• Line spacing is taken into account when using a fixed window height ([#424], [#432]).
• The new option selectrum-max-window-height can now be used to configure the maximal display window height analogue to the built-in max-mini-window-height. The new option replaces the usage of the formerly used selectrum-num-candidates-displayed setting which is now set to auto by default. By using auto the number of candidates is automatically determined using the available space and current display settings. When setting the value to a number this will determine the actual amount of displayed candidates without having an effect on the window height ([#305]).
• The option selectrum-display-style can be used to configure the display style for candidates. Vertical and horizontal display styles are included and you can cycle through styles using the new selectrum-cycle-display-style command which uses the selectrum-display-style-cycle-list option for cycling ([#305]).
• selectrum-exhibit got an optional argument which allows to keep the current candidate selected after the update which is helpful for async completions ([#306], [#307], [#349]).
• The user option selectrum-display-action can be used to show candidates in another window or frame ([#230], [#309]).
• The user option selectrum-show-indices can now be a function that can be used to control the display of the a candidate's index ([#200]).
• The user option selectrum-extend-current-candidate-highlight determines whether to extend the highlighting of the current candidate until the margin (the default is nil). See [#208].
• The user option selectrum-complete-in-buffer can be used to control whether Selectrum should handle in buffer completion (the default is t) ([#261]).
• The user option selectrum-default-value-format can be used to specify the formatting of the default value indicator ([#445]).

Enhancements

• When hovering over candidates with the mouse there are no messages shown anymore which avoids interference with candidates display ([#452]).
• The variable selectrum-should-sort-p and selectrum-active-p have been marked deprecated. You should use the new selectrum-should-sort and selectrum-is-active. selectrum-should-sort is also exposed as a user option now ([#441]).
• The variable selectrum-move-default-candidate can be used to configure how the UI handles the default value ([#441]).
• The command selectrum-repeat can also repeat the last recursive session now ([#322], [#440]).
• The default value of selectrum-extend-current-candidate-highlight has been changed to auto which will automatically extend the highlighting if the session uses annotations ([#427], [#430]).
• The accessibility of the default value in file completions has been improved. When the default exists in the prompting directory it gets sorted first otherwise the default is included as a virtual candidate ([#400], [#420], [#421]).
• Depending on the used font and display settings like line-spacing the minibuffer height could be slightly off so that the displayed candidates wouldn't be completely visible, which has been fixed ([#303], [#414]).
• The sorting of passed defaults for file completions has been improved such that paths like "/home/user/default", "~/default" or a relative passed default get sorted first when they exist within the prompting directory ([#402], [#404]).
• Tramp completions have been improved. You now get completion for tramp methods and hosts. If a connection hasn't been established yet and you are manually typing the path, a message is shown that you can refresh using selectrum-insert-current-candidate which helps correcting typos before trying to establish a new connection. Lastly if tramp would error or you would quit from a password prompt Selectrum stopped working until you restarted the session, which has been fixed ([#392], [#394], [#405], [#408]).
• Selectrum will allow recursive sessions for selectrum-completion-in-region and selectrum-select-from-history so these commands work even if enable-recursive-minibuffers is not set by the user ([#100], [#397]).
• In file completions where the directory path of the input does not exist, the candidates are automatically gathered by interpreting the input as an partial-completion style input pattern (see completion-styles-alist). For example the input "/us/l/bi/" would give results for "/usr/local/bin/". With tramp paths this has to be triggered manually using selectrum-insert-current-candidate to avoid possible speed problems ([#390], [#393]).
• You can now complete environment variables in file completions by typing a "$" after a "/" ([#386], [#389]).
• The selectrum-select-from-history command has been improved. You can now insert a history item into the previous session using your default binding for selectrum-insert-current-candidate. To submit the history item and exit use selectrum-select-current-candidate ([#362]).
• When using commands where the prompt would exceed the window width the horizontal scroll wouldn't reset afterwards when a smaller element was pulled into the prompt under certain conditions (for example when using history commands), which has been fixed ([#360]).
• When the prompt is empty and the default value is shown you can now insert it using selectrum-insert-current-candidate. Also selectrum-insert-current-candidate now moves point to end of the prompt even when there were no candidate insertion to have consistent UI behaviour ([#359], [#369]).
• selectrum-insert-current-candidate will reset minibuffer-history-position, so that after "choosing" an item and using other history commands in succession the history will start from the beginning ([#361], [#368]).
• History commands don't automatically trigger a refresh for tramp paths. This is useful to prevent unintended opening of tramp connections. To trigger a refresh for the selected tramp path you can use selectrum-insert-current-candidate ([#358], [#361], [#365], [#367], [#368], [#372]).
• In file completions the prompt will also be selected when a match is required and the path exists ([#357]).
• Improved selection behaviour for history commands. When using next-history-element, previous-history-element or isearch for history browsing the inserted history element will get selected when a match isn't required ([#323], [#324], [#341], [#346], [#380]).
• Improved exit behaviour of selectrum-select-current-candidate. The commands gives feedback now when match is required and submission not possible. Also it allows submission of the prompt when a match is required and the prompt is a member of candidates ([#338]).
• You can now configure the initial filtering for candidates in selectrum-completion-in-region using selectrum-completion-in-region-styles ([#331], [#356]).
• Computation of candidates is faster for describe-variable ([#312], [#316], [#320], [#321], [#343]).
• Candidates of completing-read-multiple which are submitted by selectrum-select-current-candidate are now passed to selectrum-candidate-selected-hook one by one in the order they were added. Before the hook would not run for the multi candidates case ([#296]).
• File completions are faster because the internal handling was updated ([#334], [#335], [#339]). Most notably recomputation only happens on directory change now. Before, the candidates where recomputed on each input change which could slow down file completions significantly for cases where read-file-name-internal would be slow already ([#210], [#276], [#277]).
• You can now give a prefix argument to selection moving commands ([#275]).
• If completion table metadata or completion-extra-properties define an affixation-function (introduced in Emacs 28) Selectrum will use this information to annotate the candidates accordingly ([#240], [#271], [#286], [#288], [#289]).
• The argument passed to selectrum-select-current-candidate and selectrum-insert-current-candidate is now used to choose the nth displayed candidate instead of calculating an index based on the currently selected candidate ([#194], [#215]).
• selectrum-insert-current-candidate no longer adds inserted candidates to the history ([#212], [#213]).
• Selectrum now by default shows indices relative to displayed candidates ([#200]).
• Selectrum now uses the initial-input argument passed to completing-read which was ignored before ([#254]).
• The prompt gets initially selected now when it equals the default value. This aligns with Selectrum's behavior of sorting the default first and will also make such prompts behave like in default Emacs completion where you can immediately submit the initial input ([#253]).
• In buffer file completions act like normal completion now and insert the candidate without prompting if there is only one. You can drop into the minibuffer by triggering the completion again ([#261]).
• The mark is pushed at the beginning of the candidate inserted by in buffer completion so you can easily jump there ([#261]).
• When the prompt is selected``selectrum-insert-current-candidate` will now switch the selection to the first candidate. Before the prompt was reinserted in place so it did not have any useful effect ([#263]).
• Default settings of selectrum-multiline-display-settings have been improved. There is now also a displayed line count by default which can be configured as well ([#266], [#302], [#318], [#398]).

Bugs fixed

• Candidate parts which used the display property wouldn't be correctly highlighted on selection, which has been fixed ([#411], [#413]).
• The minibuffer prompt face would bleed into the candidates when the candidate strings used the display property, which has been fixed ([#235], [#413]).
• Selectrum would error when providing a list as default value in file completions, which has been fixed ([#401], [#402]).
• Selectrum did not set minibuffer-default for the current completion session, which has been fixed ([#350], [#352], [#354]).
• When there were no candidates selectrum-get-current-candidate would throw an error, which has been fixed ([#347], [#348]).
• There were UI and display problems when the prompt width exceeded the available window width. When auto-hscroll-mode was set to current-line it would introduce constant back and forth scrolling issues and other values also wouldn't allow to use such a prompt correctly ([#344], [#345], [#374], [#375], [#377], [#378], [#379], [#381]).
• selectrum-select-from-history set variables selectrum-should-sort-p, selectrum-candidate-inserted-hook, selectrum-candidate-selected-hook and enable-recursive-minibuffers for subsequent recursive sessions, which has been fixed. It is also enhanced to trigger an error when called outside the minibuffer now [#337].
• selectrum-completion-in-region could trigger an error when completion-all-completions would be called within a session, which has been fixed ([#315], [#329]).
• selectrum-select-from-history wasn't autoloaded which would trigger an error when used before Selectrum was loaded, this has been fixed ([#310], [#328]).
• When let binding minibuffer-message-timeout around minibuffer-message within Selectrum sessions the value wouldn't be applied, which has been fixed ([#327]).
• minibuffer-default is now treated as the default when set, before it would have no effect. When a list the car is used as default as of now ([#324]).
• selectrum-extend-current-candidate-highlight, selectrum-show-indices, selectrum-right-margin-padding and selectrum-multiline-display-settings wouldn't use the local session bindings if there were any, which has been fixed ([#317]).
• selectrum-insert-current-candidate would duplicate the prompt for completing-read-multiple when the prompt was selected, which has been fixed. The behavior is now like in completing-read ([#296]).
• selectrum-select-current-candidate did not work correctly for completing-read-multiple when the prompt was submitted, which has been fixed ([#285], [#296]).
• selectrum-candidate-inserted-hook would run after using selectrum-insert-current-candidate with a selected prompt, which has been fixed ([#296]).
• Passing a symbol or a list of symbols to completing-read as default value DEF would trigger an error, which has been fixed. Selectrum now behaves like completind-read-default and returns the symbol (or the first in case of a list) ([#291], [#295]).
• selectrum-active-p would wrongly report an active status for recursive minibuffer session with Selectrum turned off, which has been fixed ([#293]).
• For in buffer file completions s-expression commands for path level navigation did not work which has been fixed ([#261]).
• Do not insert spaces after path completion in comint buffers ([#261])].
• The return value of selectrum-completion-in-region has been fixed according to the documented API of completion-in-region ([#251]).
• When strings of Selectrum display properties or completion table annotations have a face defined it gets used. Before those faces would be ignored ([#236], [#250]).
• Selectrum's internal minibuffer setup hook now runs after any other functions added to minibuffer-setup-hook. Before, you couldn't set selectrum-should-sort-p locally via minibuffer-with-setup-hook to adjust sorting for a single selectrum-read session ([#242]).
• selectrum-completion-in-region no longer unsets selectrum-should-sort-p for all recursive minibuffer sessions in the case the initial completion table specified its own display-sort-function ([#221]).
• The candiate list returned from a dynamic candidate function passed to selectrum-read is now also prevented to be modified in case it's a list of strings. Before the list only wasn't modfied when the function returned the alist format as specified by selectrum-read ([#220]).
• Annotations or usage or selectrum-candidate-display-suffix property in file completions were overwritten for directories and not displayed, which has been fixed ([#256], [#255]).
• selectrum-repeat did not set this-command when calling the last command, which has been fixed ([#438], [#439]).