GNU-devel ELPA - orderless

Each component of a pattern can match in any of several matching styles. A matching style is a function from strings to regexps or predicates, so it is easy to define new matching styles. The value returned by a matching style can be either a regexp as a string, an s-expression in rx syntax or a predicate function. The predefined matching styles are:

orderless-regexp

the component is treated as a regexp that must match somewhere in the candidate.

If the component is not a valid regexp, it is ignored.

orderless-literal

the component is treated as a literal string that must occur in the candidate.

orderless-literal-prefix

the component is treated as a literal string that must occur as a prefix of a candidate.

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 matches query-replace-regexp, recode-region and magit-remote-list-refs; f-d.t matches final-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-flex

the characters of the component should appear in that order in the candidate, but not necessarily consecutively.

This maps abc to a.*b.*c.

orderless-without-literal

the component is a treated as a literal string that must not occur in the candidate.

Nothing is highlighted by this style. This style should not be used directly in orderless-matching-styles but with a style dispatcher instead. See also the more general style modifier orderless-not.

The variable orderless-matching-styles can be set to a list of the desired matching styles to use. By default it enables the literal and regexp styles.

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.

Orderless allows the definition of custom completion styles using the orderless-define-completion-style macro. Any Orderless configuration variable can be adjusted locally for the new style, e.g., orderless-matching-styles.

By default Orderless only enables the regexp and literal matching styles. In the following example an orderless+initialism style is defined, which additionally enables initialism matching. This completion style can then used when matching candidates of the symbol or command completion category.

(orderless-define-completion-style orderless+initialism
  (orderless-matching-styles '(orderless-initialism
			       orderless-literal
			       orderless-regexp)))
(setq completion-category-overrides
      '((command (styles orderless+initialism))
	(symbol (styles orderless+initialism))
	(variable (styles orderless+initialism))))

Note that in order for the orderless+initialism style to kick-in with the above configuration, you'd need to use commands whose metadata indicates that the completion candidates are commands or symbols. In Emacs 28, execute-extended-command has metadata indicating you are selecting a command, but earlier versions of Emacs lack this metadata. Activating marginalia-mode from the Marginalia package provides this metadata automatically for many built-in commands and is recommended if you use the above example configuration, or other similarly fine-grained control of completion styles according to completion category.

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 predicate and a list of regexps to match against, configured using orderless-matching-styles, is probably flexible enough for the vast majority of users. The patterns are compiled by orderless-compile. Under special circumstances it may be useful to implement a custom pattern compiler by advising orderless-compile.

You might want to change the separator or the matching style configuration on the fly while matching. There many possible user interfaces 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. Since there are so many possible UIs and which to use is mostly a matter of taste, orderless does not provide any such commands. But it's easy to write your own!

For example, say you want to use the keybinding C-l to make all components match literally. You could use the following code:

(defun my/match-components-literally ()
  "Components match literally for the rest of the session."
  (interactive)
  (setq-local orderless-matching-styles '(orderless-literal)
	      orderless-style-dispatchers nil))

(define-key minibuffer-local-completion-map (kbd "C-l")
  #'my/match-components-literally)

Using setq-local to assign to the configuration variables ensures the values are only used for that minibuffer completion session.

To use orderless from Ivy add this to your Ivy configuration:

(setq ivy-re-builders-alist '((t . orderless-ivy-re-builder)))
(add-to-list 'ivy-highlight-functions-alist '(orderless-ivy-re-builder . orderless-ivy-highlight))

To use orderless from Helm, simply configure orderless as you would for completion UIs that use Emacs completion styles and add this to your Helm configuration:

(setq helm-completion-style 'emacs)

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:

1. 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 "[ &]")
   

2. The matching portions of candidates aren't highlighted. That's because company-capf is hard-coded to look for the completions-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?)

If you would like to use different completion-styles with company-capf instead, you can add this to your configuration:

;; We follow a suggestion by company maintainer u/hvis:
;; https://www.reddit.com/r/emacs/comments/nichkl/comment/gz1jr3s/
(defun company-completion-styles (capf-fn &rest args)
  (let ((completion-styles '(basic partial-completion)))
    (apply capf-fn args))

(advice-add 'company-capf :around #'company-completion-styles)

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 any completion UI supporting completion styles 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 default tab completion, Icomplete or other UIs supporting completion styles! (Ivy does not provide a completion style to my knowledge.) So, for example, Icomplete users could, instead of using this package, install Helm and configure Icomplete to use it as follows:

(require 'helm)
(setq completion-styles '(helm basic))
(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. It offers a completion-style that can be used with Emacs' default completion UI, Mct, Vertico or with Icomplete. Furthermore Ivy is supported. The components can be matched literally, as regexps, as initialisms or in the flex style (called "fuzzy" in prescient). Prescient does not offer the same flexibility as Orderless with its style dispatchers. However in addition to matching, Prescient supports sorting of candidates, while 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 to S-SPC, to do it.
• Ido has ido-restrict-to-matches and binds it to C-SPC.
• Ivy has ivy-restrict-to-matches, bound to S-SPC, so you can get the effect of out of order matching without using ivy--regex-ignore-order.