* Overview

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.

Completion styles like =orderless= are used as entries in the variables
=completion-styles= and =completion-category-overrides=, see their
documentation. These completions styles 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).

So to test this completion method you can put =orderless.el= somewhere
on your =load-path=, and use the following configuration:

#+begin_src emacs-lisp
(require 'orderless)
(setq completion-styles '(orderless))
(icomplete-mode) ; optional but recommended!
#+end_src

(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 [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]].

Bug reports are highly welcome and appreciated!

* Customization

** Component matching styles

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-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-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=.

The variable =orderless-component-matching-style= should be set to a
list of the desired styles to use. By default it enables the regexp
and initialism styles.

** Component separator regexp

The pattern components are space-separated by default: this is
controlled by the variable =orderless-regexp-separator=, which should be
set to a regexp that matches the desired component separator. The
default value matches a sequence of spaces. It may be useful to add
hyphens or slashes (or both), to match symbols or file paths,
respectively.

If you are implementing a command for which you know you want a
different separator for the components, bind
=orderless-regexp-separator= in a =let= form.

The package also provides a command
=orderless-temporarily-change-separator= to change it for the rest of
the current completion session. If you want to use it, bind it to a
key in a keymap that will be active during your completion session:

- Icomplete users should bind it in =icomplete-minibuffer-map=.
- Users of the default completion should bind it in both
  =minibuffer-local-completion-map= and
  =minibuffer-local-filename-completion-map=.

** Faces for component matches

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.

* Related packages

** Ivy and Helm

The well-known and hugely powerful completion frameworks [[https://github.com/abo-abo/swiper][Ivy]] and [[https://github.com/emacs-helm/helm][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:

#+begin_src emacs-lisp
  (require 'helm)
  (setq completion-styles '(helm))
  (icomplete-mode)
#+end_src

(Of course, if you install Helm, you might as well use the Helm UI in
=helm-mode= rather than Icomplete.)

** Prescient

The [[https://github.com/raxod502/prescient.el][prescient.el]] library also provides matching of space-separated
components in any order and it can be used with either the [[https://github.com/raxod502/selectrum][Selectrum]]
or [[https://github.com/abo-abo/swiper][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).