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.
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
prescient.el
is available on MELPA as four separate packages (one
for the library, and the rest for integrating with other frameworks):
The easiest way to install these packages is using
straight.el
:
(straight-use-package 'prescient)
(straight-use-package 'ivy-prescient)
(straight-use-package 'company-prescient)
(straight-use-package 'selectrum-prescient)
However, you may install using any other package manager if you prefer.
Usage
- To cause Ivy to use
prescient.el
sorting and filtering, enableivy-prescient-mode
. - To cause Company to use
prescient.el
sorting, enablecompany-prescient-mode
. - To cause Selectrum to use
prescient.el
sorting and filtering, enableselectrum-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. The query is first split on spaces into subqueries (two
consecutive spaces match a literal space). Each subquery filters the
candidates because it 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
). 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
don't like the algorithm used for filtering, you can choose a
different one by customizing prescient-filter-method
.
Configuration
-
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 whenprescient-persist-mode
is active. The default value follows the conventions ofno-littering
. -
prescient-filter-method
: A list of algorithms to use for filtering candidates. The default isliteral
,regexp
, andinitialism
as described above, but you can also use substring matching, initialism matching, regexp matching, fuzzy matching, prefix matching, or any combination of those. See the docstring for full details. -
ivy-prescient-sort-commands
: By default, all commands have their candidates sorted. You can override this behavior by customizingivy-prescient-sort-commands
. See the docstring. -
ivy-prescient-retain-classic-highlighting
: By default, the highlighting behavior ofivy-prescient.el
is slightly different from Ivy's highlighting forivy--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, thenivy-prescient.el
does not applyprescient.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, thenivy-prescient.el
does not applyprescient.el
sorting to Ivy. See the Ivy documentation for information on how Ivy sorts by default, and how to customize it manually.
Contributor guide
Please see the contributor guide for my projects.