README.md

prescient.el: simple but effective sorting and filtering for Emacs.

Summary

prescient.el is a library which sorts and filters lists of candidates, such as appear when you use a package like Ivy or Company. Extension packages such as ivy-prescient.el and company-prescient.el adapt the library for usage with various frameworks.

prescient.el also provides a completion style (prescient) for filtering candidates via Emacs's generic completion, such as in Icomplete, Vertico, and Corfu. These last two have extension packages to correctly set up filtering and sorting.

As compared to other packages which accomplish similar tasks, including IDO, Ivy, Helm, Smex, Flx, Historian, and Company-Statistics, prescient.el aims to be simpler, more predictable, and faster.

• Installation
• Usage
• Algorithm
• Configuration and other features
  • Faces
  • For the completion style
  • For Corfu
  • For Company
  • For Ivy
  • For Selectrum
  • For Vertico
• Contributor guide

Installation

prescient.el is available on MELPA as six separate packages (one for the library, and the rest for integrating with other frameworks):

• prescient
• corfu-prescient
• company-prescient
• ivy-prescient
• selectrum-prescient
• vertico-prescient

The easiest way to install these packages is using straight.el:

(straight-use-package 'prescient)
(straight-use-package 'corfu-prescient)
(straight-use-package 'company-prescient)
(straight-use-package 'ivy-prescient)
(straight-use-package 'selectrum-prescient)
(straight-use-package 'vertico-prescient)

However, you may install using any other package manager if you prefer.

Usage

prescient.el and the extension packages provide modes that configure filtering and/or sorting in their respective framework. These modes can have their own settings, such as ways to set up filtering but not sorting, which are described in a following section.

• To cause Emacs to use the prescient completion style for filtering, add prescient to the user option completion-styles.

• To cause Corfu to use prescient.el sorting and filtering, enable corfu-prescient-mode.

• To cause Company to use prescient.el sorting, enable company-prescient-mode.

• To cause Ivy to use prescient.el sorting and filtering, enable ivy-prescient-mode.

• To cause Selectrum to use prescient.el sorting and filtering, enable selectrum-prescient-mode.

• To cause Vertico to use prescient.el sorting and filtering, enable vertico-prescient-mode.

• To cause your usage statistics to be saved between Emacs sessions, enable prescient-persist-mode.

Please note that you must load Counsel before ivy-prescient.el. This is because loading Counsel results in a number of changes being made to the user options of Ivy, which ivy-prescient.el must then undo.

Algorithm

prescient.el takes as input a list of candidates, and a query that you type.

When filtering, the query is first split on spaces into subqueries (two consecutive spaces match a literal space). Each subquery filters the candidates according to the filter methods listed in prescient-filter-method. By default, a subquery must match as either a substring of the candidate, a regexp, or an initialism (e.g. ffap matches find-file-at-point, and so does fa). A candidate must match all subqueries to pass the filter and subqueries can be matched in any order.

When sorting, the last few candidates you selected are displayed first, followed by the most frequently selected ones, and then the remaining candidates are sorted by length.

If you would like prescient.el to forget about a candidate, use the command prescient-forget.

Configuration and other features

• prescient-history-length: The number of recently selected candidates that are remembered and displayed at the top of the list.

• prescient-frequency-decay: prescient.el keeps a "frequency" for each selected candidate, which is incremented by one each time you select the candidate. To keep things tidy, frequencies are multiplied by this variable's value each time you select a new candidate, so they decrease over time.

• prescient-frequency-threshold: Once the frequency for an infrequently used command falls below the value of this variable, prescient.el forgets about it.

• prescient-save-file: Where to save statistics that are persisted between Emacs sessions when prescient-persist-mode is active. The default value follows the conventions of no-littering.

• prescient-filter-method: A list of algorithms to use for filtering candidates. The default is literal, regexp, and initialism as described above, but you can also use substring matching, initialism matching, regexp matching, fuzzy matching, prefix matching, anchored matching, literal-prefix matching, or any combination of those. See the docstring for full details.

• prescient-filter-alist: An alist of symbol-function pairs that associate a symbol in prescient-filter-method with a function that creates a regexp for matching a candidate. You can add to this alist to define your own custom filter methods, and use them by adding the appropriate symbol to prescient-filter-method.

• prescient-sort-full-matches-first: Whether prescient.el sorts candidates that are fully matched before candidates that are partially matched. This user option affects:

  • corfu-prescient.el
  • company-prescient.el for Company backends that used the prescient completion style for filtering
  • selectrum-prescient.el
  • vertico-prescient.el

• prescient-sort-length-enable: Whether to sort the candidates by length in addition to recency and frequency.

• prescient-tiebreaker: Function to use for breaking ties in recency instead of length.

• prescient-use-char-folding: Whether the literal and literal-prefix filter methods use character folding.

• prescient-use-case-folding: Whether filtering methods use case folding (in non-Emacs terms, whether they are case insensitive). This can be one of nil, t, or smart (the default). If smart, then case folding is disabled when upper-case characters are used.

• Quickly adjusting filtering: Commands are available to temporarily toggle filter methods on or off while you're completing candidates. These commands are similar in usage to Isearch's own toggling commands, except that multiple filtering methods can be active at the same time.

  For example, to toggle regexp filtering on or off (perhaps you're searching for a long/complex candidate), you can press M-s r. If you wish to use only regexp filtering, you can use C-u M-s r to unconditionally turn on regexp filtering and turn off all other methods. This toggling is a buffer-local effect, and does not change the default filtering behavior. For that, customize prescient-filter-method.

  selectrum-prescient.el and vertico-prescient.el will both bind commands to toggle filter methods in the current completion buffer. corfu-prescient.el will bind the commands while the Corfu pop-up is active. While the integration mode is enabled, M-s is bound to prescient-toggle-map in the completion buffer or Corfu pop-up, and is used as a prefix key to access the commands.

  Key	Command
  M-s a	prescient-toggle-anchored
  M-s f	prescient-toggle-fuzzy
  M-s i	prescient-toggle-initialism
  M-s l	prescient-toggle-literal
  M-s p	prescient-toggle-prefix
  M-s P	prescient-toggle-literal-prefix
  M-s r	prescient-toggle-regexp
  M-s '	prescient-toggle-char-fold
  M-s c	prescient-toggle-case-fold

  When defining custom filter methods, you can create new bindings using prescient-create-and-bind-toggle-command, which takes an unquoted filter symbol and a string that can be used by kbd. For example,

  (prescient-create-and-bind-toggle-command my-foo "M-f")

  will bind a command for toggling the my-foo filter to M-s M-f.

Faces

prescient.el defines two faces: prescient-primary-highlight and prescient-secondary-highlight. The primary highlight is used to highlight matches in candidates. The secondary highlight is used for important sections within each matched region. For example, the initialism filter method highlights the entire match with prescient-primary-highlight and each initial in the initialism with prescient-secondary-highlight.

These faces are used by the prescient completion style (and so completion frameworks using that style, such as Corfu and Vertico) and Selectrum. ivy-prescient.el uses Ivy's faces.

The following example shows customizing these faces. I use the Zerodark color theme, which includes colors for Ivy, but not for Selectrum. I inspected the theme source code to see what colors were being used for Ivy, and copied them to be used for Selectrum as well:

(require 'zerodark-theme)

(let ((class '((class color) (min-colors 89))))
  (custom-theme-set-faces
   'zerodark
   `(selectrum-current-candidate
     ((,class (:background "#48384c"
                           :weight bold
                           :foreground "#c678dd"))))
   `(prescient-primary-highlight
     ((,class (:foreground "#da8548"))))
   `(prescient-secondary-highlight
     ((,class (:foreground "#98be65"))))))

(enable-theme 'zerodark)

For the completion style

The following user options are specific to using the prescient completion style:

• prescient-completion-highlight-matches: Whether the completion style should highlight matches in the filtered candidates using the faces prescient-primary-highlight and prescient-secondary-highlight.

For Corfu

corfu-prescient.el configures filtering locally in buffers in which corfu-mode is active. To do this, it modifies the values of completion-styles, completion-category-overrides, and completion-category-defaults. Sorting is configured globally.

The following user options are specific to using prescient.el with Corfu:

• corfu-prescient-completion-styles: What the value of completion-styles is changed to.

• corfu-prescient-completion-category-overrides: Overrides that should be included in completion-category-overrides.

• corfu-prescient-enable-filtering: If non-nil when corfu-prescient-mode is enabled, then

  • M-s is bound to prescient-toggle-map while the Corfu pop-up is active
  • completion-styles is changed to the value of corfu-prescient-completion-styles
  • completion-category-overrides is changed to include overrides in corfu-prescient-completion-category-overrides
  • completion-category-defaults is set to nil

• corfu-prescient-enable-sorting: If non-nil when corfu-prescient-mode is enabled, then corfu-sort-function is set to the function prescient-completion-sort.

• corfu-prescient-override-sorting: If non-nil when corfu-prescient-mode is enabled, then corfu-sort-override-function is set to the function prescient-completion-sort and corfu-prescient-enable-sorting is made non-nil.

For Company

The following user options are specific to using prescient.el sorting with Company:

• company-prescient-sort-length-enable: By default, the standard prescient.el sorting algorithm is used for all Company completions when company-prescient-mode is enabled. However, this algorithm is inappropriate in some situations. In particular, some Company backends return fuzzy-matched candidates with an intelligent sorting pre-applied. In this case, the fallback sorting by length that prescient.el does will just make a giant mess of things. By customizing this user option to nil for such Company backends (see Radian for an example), you can avoid the problem. Then prescient.el will helpfully move recently and frequently used candidates to the top of the completions list, but otherwise leave candidate ordering alone.

For Ivy

The following user options are specific to using prescient.el with Ivy:

• ivy-prescient-sort-commands: By default, all commands have their candidates sorted. You can override this behavior by customizing ivy-prescient-sort-commands. See the docstring.

• ivy-prescient-retain-classic-highlighting: By default, the highlighting behavior of ivy-prescient.el is slightly different from Ivy's highlighting for ivy--regex-ignore-order. You can recover the original behavior by customizing this user option; see the docstring for more details.

• ivy-prescient-enable-filtering: If set to nil, then ivy-prescient.el does not apply prescient.el filtering to Ivy. See the Ivy documentation for information on how Ivy filters by default, and how to customize it manually.

• ivy-prescient-enable-sorting: If set to nil, then ivy-prescient.el does not apply prescient.el sorting to Ivy. See the Ivy documentation for information on how Ivy sorts by default, and how to customize it manually.

For Selectrum

The following user options are specific to using prescient.el with Selectrum:

• selectrum-prescient-enable-filtering: If set to nil, then selectrum-prescient.el does not change filtering of Selectrum. See the Selectrum documentation for information on how Selectrum configures filtering by default, and how to customize it manually.

  Additionally, when set, the matched part of each candidate is highlighted using the faces described above.

• selectrum-prescient-enable-sorting: If set to nil, then selectrum-prescient.el does not change sorting of Selectrum. See the Selectrum documentation for information on how Selectrum configures sorting by default, and how to customize it manually.

For Vertico

vertico-prescient.el configures filtering locally in the Vertico buffer. To do this, it modifies the values of completion-styles, completion-category-overrides, and completion-category-defaults. Sorting is configured globally.

The following user options are specific to using prescient.el with Vertico:

• vertico-prescient-completion-styles: What the value of completion-styles is changed to.

• vertico-prescient-completion-category-overrides: Overrides that should be included in completion-category-overrides.

• vertico-prescient-enable-filtering: If non-nil when vertico-prescient-mode is enabled, then

  • M-s is bound to prescient-toggle-map
  • completion-styles is changed to the value of vertico-prescient-completion-styles
  • completion-category-overrides is changed to include overrides in vertico-prescient-completion-category-overrides
  • completion-category-defaults is set to nil

• vertico-prescient-enable-sorting: If non-nil when vertico-prescient-mode is enabled, then vertico-sort-function is set to the function prescient-completion-sort.

• vertico-prescient-override-sorting: If non-nil when vertico-prescient-mode is enabled, then vertico-sort-override-function is set to the function prescient-completion-sort and vertico-prescient-enable-sorting is made non-nil.

Compatibility with other packages

For use with completion-preview-mode in Emacs 30:

(setq completion-preview-sort-function #'prescient-completion-sort)

Contributor guide

Please see the contributor guide for my projects.