This package provides an orderless
completion style that divides the
pattern into space-separated components, and matches candidates that
match all of the components in any order. Each component can match in
any one of several ways: literally, as a regexp, as an initialism, in
the flex style, or as multiple word prefixes. By default, regexp and
initialism matches are enabled.
A completion style is a back-end for completion and is used from a
front-end that provides a completion UI. Any completion style can be
used with the default Emacs completion UI (sometimes called minibuffer
tab completion) or with the built-in Icomplete package (which is
similar to the more well-known Ido Mode). To use a completion style in
this fashion simply add it as an entry in the variables
completion-styles
and completion-category-overrides
(see their
documentation).
With a bit of effort, it might still be possible to use orderless
with
other completion UIs, even if those UIs don’t support the standard
Emacs completion styles. Currently there is support for Ivy and
Selectrum (see below).
If you use MELPA, the easiest way to install orderless
is via
package-install
. If you use both MELPA and use-package
, you can use:
(use-package orderless
:ensure t
:init (icomplete-mode) ; optional but recommended!
:custom (completion-styles '(orderless)))
Alternatively, put orderless.el
somewhere on your load-path
, and use
the following configuration:
(require 'orderless)
(setq completion-styles '(orderless))
(icomplete-mode) ; optional but recommended!
(And of course, if you use another completion framework such as Ivy or Helm, disable it.)
If you like the experience of using orderless
with Icomplete, but wish
the candidates displayed vertically, you can use icomplete-vertical.
Bug reports are highly welcome and appreciated!
This is what it looks like to use describe-function
(bound by default
to C-h f
) to match eis ff
. Notice that in this particular case eis
matched as an initialism, and ff
matched as a regexp. The completion
UI in the screenshot is icomplete-vertical and the theme is
Protesilaos Stavrou’s lovely modus-operandi.
Each component of a pattern can match in any of several matching styles. A matching style is simply a function from strings to strings that maps a component to a regexp to match against, so it is easy to define new matching styles. The predefined ones are:
- orderless-regexp
- the component is treated as a regexp that must
match somewhere in the candidate.
This is simply the identity function!
- orderless-literal
- the component is treated as a literal string
that must occur in the candidate.
This is just
regexp-quote
. - orderless-without-literal
- the component is a treated as a literal
string that must not occur in the candidate.
Note that nothing is highlighted for this matching style. You probably don’t want to use this style directly in
orderless-matching-styles
but with a style dispatcher instead. There is an example in the section on style dispatchers. - orderless-prefixes
- the component is split at word endings and
each piece must match at a word boundary in the candidate, occurring
in that order.
This is similar to the built-in
partial-completion
completion-style. For example,re-re
matchesquery-replace-regexp
,recode-region
andmagit-remote-list-refs
;f-d.t
matchesfinal-draft.txt
. - orderless-initialism
- each character of the component should appear
as the beginning of a word in the candidate, in order.
This maps
abc
to\<a.*\<b.*\c
. - orderless-strict-initialism
- like initialism but only allow
non-letters in between the matched words.
For example
fb
would matchfoo-bar
but notfoo-qux-bar
. - orderless-strict-leading-initialism
- like strict-initialism but
require the first initial to match the candidate’s first word.
For example
bb
would matchbar-baz
but notfoo-bar-baz
. - orderless-strict-full-initialism
- like strict-initialism but
require the first initial to match the candidate’s first word and the
last initial to be at the final word.
For example
fbb
would matchfoo-bar-baz
but notfoo-bar-baz-qux
. - orderless-flex
- the characters of the component should appear in
that order in the candidate, but not necessarily consecutively.
This maps
abc
toa.*b.*c
.
The variable orderless-matching-styles
can be set to a list of the
desired matching styles to use. By default it enables the regexp and
initialism styles.
For more fine-grained control on which matching styles to use for
each component of the input string, you can customize the variable
orderless-style-dispatchers
.
Style dispatchers are functions which take a component, its index in the list of components (starting from 0), and the total number of components, and are used to determine the matching styles used for that specific component, overriding the default matching styles.
A style dispatcher can either decline to handle the input string or
component, or it can return which matching styles to use. It can
also, if desired, additionally return a new string to use in place of
the given one. Consult the documentation of orderless-dispatch
for
full details.
As an example, say you wanted the following setup:
- you normally want components to match as regexps,
- except for the first component, which should always match as an
initialism —this is pretty useful for, say,
execute-extended-command
(M-x
) ordescribe-function
(C-h f
), - later components ending in
~
should match (the characters other than the final~
) in the flex style, and - later components starting with
!
should indicate the rest of the component is a literal string not contained in the candidate.
You can achieve this with the following configuration:
(defun flex-if-twiddle (pattern _index _total)
(when (string-suffix-p "~" pattern)
`(orderless-flex . ,(substring pattern 0 -1))))
(defun first-initialism (pattern index _total)
(if (= index 0) 'orderless-initialism))
(defun without-if-bang (pattern _index _total)
(when (string-prefix-p "!" pattern)
`(orderless-without-literal . ,(substring pattern 1))))
(setq orderless-matching-styles '(orderless-regexp)
orderless-style-dispatchers '(first-initialism
flex-if-twiddle
without-if-bang))
The pattern components are space-separated by default: this is
controlled by the variable orderless-component-separator
, which should
be set either to a regexp that matches the desired component
separator, or to a function that takes a string and returns the list
of components. The default value is a regexp matches a non-empty
sequence of spaces. It may be useful to add hyphens or slashes (or
both), to match symbols or file paths, respectively.
Even if you want to split on spaces you might want to be able to
escape those spaces or to enclose space in double quotes (as in shell
argument parsing). For backslash-escaped spaces set
orderless-component-separator
to the function
orderless-escapable-split-on-space
; for shell-like double-quotable
space, set it to the standard Emacs function split-string-and-unquote
.
If you are implementing a command for which you know you want a
different separator for the components, bind
orderless-component-separator
in a let
form.
The portions of a candidate matching each component get highlighted in
one of four faces, orderless-match-face-?
where ?
is a number from 0
to 3. If the pattern has more than four components, the faces get
reused cyclically.
If your completion-styles
(or completion-category-overrides
for some
particular category) has more than one entry, remember than Emacs
tries each completion style in turn and uses the first one returning
matches. You will only see these particular faces when the orderless
completion is the one that ends up being used, of course.
The default mechanism for turning an input string into a list of
regexps to match against, configured using orderless-matching-styles
,
is probably flexible enough for the vast majority of users. But if you
want to completely change the mechanism, customize the
orderless-pattern-compiler
. It’s value should be a function from
string to lists of regexps. You might find it convenient to use
orderless-default-pattern-compiler
as a subroutine in your own pattern
compiler, it conveniently accepts optional arguments that specify
lists to use instead of orderless-matching-styles
.
You might want to change the separator or the matching style configuration on the fly while matching. There many possible UIs for this: you could toggle between two chosen configurations, cycle among several, have a keymap where each key sets a different configurations, have a set of named configurations and be prompted (with completion) for one of them, popup a hydra to choose a configuration, etc.
Rather than include commands for any of those on-the-fly configuration
changes, orderless
provides a general mechanism to make it easy to
write such commands yourself. For each variable you might to
temporarily change there is a corresponding transient variable that
overrides it when the transient variable is non-nil. You can write
your own commands to set these transient variable to the desired value
without clobbering the value of the variables they override. To reset
the transient variables to nil
again after each completion session,
use the following configuration:
(add-hook 'minibuffer-exit-hook
#'orderless-remove-transient-configuration)
The transient variables provided are:
orderless-transient-component-separator
orderless-transient-matching-styles
orderless-transient-style-dispatchers
For example, say you want to use the keybinding C-l
to make all
components match literally. You could use the following configuration:
(defun my/match-components-literally ()
"Components match literally for the rest of the session."
(interactive)
(setq orderless-transient-matching-styles '(orderless-literal)
orderless-transient-style-dispatchers '(ignore)))
(add-hook 'minibuffer-exit-hook
#'orderless-remove-transient-configuration)
(define-key minibuffer-local-completion-map (kbd "C-l")
#'my/match-components-literally)
Note that we also set orderless-transient-style-dispatchers
to
'(ignore)
, to ensure no style dispatchers are used so the literal
matching does not get overridden. You may want to allow the
dispatchers in orderless-style-dispatchers
to override, in which case
you’d set orderless-transient-style-dispatchers
to nil
or simply
remove that assignment.
Several excellent completion UIs exist for Emacs in third party packages. They do have a tendency to forsake standard Emacs APIs, so integration with them must be done on a case by case basis.
If you manage to use orderless
with a completion UI not listed here,
please file an issue or make a pull request so others can benefit from
your effort. The functions orderless-filter
,
orderless-highlight-matches
, orderless--highlight
and
orderless--component-regexps
are likely to help with the
integration.
To use orderless
from Ivy add this to your Ivy configuration:
(setq ivy-re-builders-alist '((t . orderless-ivy-re-builder)))
To use orderless
from Selectrum add this to your Selectrum
configuration:
(setq selectrum-refine-candidates-function #'orderless-filter)
(setq selectrum-highlight-candidates-function #'orderless-highlight-matches)
Company comes with a company-capf
backend that uses the
completion-at-point functions, which in turn use completion styles.
This means that the company-capf
backend will automatically use
orderless
, no configuration necessary!
But there are a couple of points of discomfort:
- Pressing SPC takes you out of completion, so with the default
separator you are limited to one component, which is no fun. To fix
this add a separator that is allowed to occur in identifiers, for
example, for Emacs Lisp code you could use an ampersand:
(setq orderless-component-separator "[ &]")
- The matching portions of candidates aren’t highlighted. That’s
because
company-capf
is hard-coded to look for thecompletions-common-part
face, and it only use one face,company-echo-common
to highlight candidates.So, while you can’t get different faces for different components, you can at least get the matches highlighted in the sole available face with this configuration:
(defun just-one-face (fn &rest args) (let ((orderless-match-faces [completions-common-part])) (apply fn args))) (advice-add 'company-capf--candidates :around #'just-one-face)
(Aren’t dynamically scoped variables and the advice system nifty?)
The well-known and hugely powerful completion frameworks Ivy and Helm
also provide for matching space-separated component regexps in any
order. In Ivy, this is done with the ivy--regex-ignore-order
matcher.
In Helm, it is the default, called “multi pattern matching”.
This package is significantly smaller than either of those because it solely defines a completion style, meant to be used with the built-in Icomplete completion UI, while both of those provide their own completion UI (and many other cool features!).
It is worth pointing out that Helm does provide its multi pattern matching as a completion style which could be used with Icomplete! (Ivy does not.) So, Icomplete users could, instead of using this package, install Helm and configure Icomplete to use it as follows:
(require 'helm)
(setq completion-styles '(helm))
(icomplete-mode)
(Of course, if you install Helm, you might as well use the Helm UI in
helm-mode
rather than Icomplete.)
The prescient.el library also provides matching of space-separated
components in any order and it can be used with either the Selectrum
or Ivy completion UIs (it does not offer a completion-style that
could be used with Emacs’ default completion UI or with Icomplete).
The components can be matched literally, as regexps, as initialisms or
in the flex style (called “fuzzy” in prescient). In addition to
matching, prescient.el
also supports sorting of candidates (orderless
leaves that up to the candidate source and the completion UI).
An effect equivalent to matching multiple components in any order can
be achieved in completion frameworks that provide a way to restrict
further matching to the current list of candidates. If you use the
keybinding for restriction instead of SPC
to separate your components,
you get out of order matching!
- Icicles calls this progressive completion and uses the
icicle-apropos-complete-and-narrow
command, bound toS-SPC
, to do it. - Ido has
ido-restrict-to-matches
and binds it toC-SPC
. - Ivy has
ivy-restrict-to-matches
, bound toS-SPC
, so you can get the effect of out of order matching without usingivy--regex-ignore-order
.