path: root/README.org

* Overview
:PROPERTIES:
:TOC: :include all :ignore this
:END:

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 
[[https://github.com/abo-abo/swiper][Ivy]] and 
[[https://github.com/raxod502/selectrum][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:

#+begin_src emacs-lisp
  (use-package orderless
    :ensure t
    :init (icomplete-mode) ; optional but recommended!
    :custom (completion-styles '(orderless)))
#+end_src

Alternatively, 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!

:CONTENTS:
- [[#screenshot][Screenshot]]
- [[#customization][Customization]]
  - [[#component-matching-styles][Component matching styles]]
    - [[#style-dispatchers][Style dispatchers]]
  - [[#component-separator-regexp][Component separator regexp]]
  - [[#faces-for-component-matches][Faces for component matches]]
  - [[#pattern-compiler][Pattern compiler]]
  - [[#interactively-changing-the-configuration][Interactively changing the configuration]]
- [[#related-packages][Related packages]]
  - [[#ivy-and-helm][Ivy and Helm]]
  - [[#prescient][Prescient]]
  - [[#icicless-progressive-matching][Icicles's progressive matching]]
- [[#integration-with-other-completion-uis][Integration with other completion UIs]]
  - [[#ivy][Ivy]]
  - [[#selectrum][Selectrum]]
:END:

** Screenshot

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 [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] and the theme is
Protesilaos Stavrou's lovely [[https://gitlab.com/protesilaos/modus-themes][modus-operandi]].

[[images/describe-function-eis-ff.png]]

* 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-strict-initialism :: like initialism but only allow
  non-letters in between the matched words.

	For example =fb= would match =foo-bar= but not =foo-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 match =bar-baz= but not =foo-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 match =foo-bar-baz= but not =foo-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= 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-styles= can be set to a list
of the desired matching styles to use. By default it enables the
regexp and initialism styles. 

That variable, in addition to matching styles, can contain dispatchers
that can change which styles are used depending on the actual input
string.

*** Style dispatchers

 For more fine-grained control on which matching styles to use for
 each component of the input string, you can add use /style
 dispatchers/. These are also specified in the variable
 =orderless-component-matching-styles= whose full syntax is:

 =(= /matching-styles/... =:dispatchers= /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=) or =describe-function= (=C-h f=),
 - and any later component ending in =~= should match (the characters
   other than the final =~=) in the flex style.

 You can achieve this with the following configuration:

 #+begin_src emacs-lisp
   (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))

   (setq orderless-component-matching-styles
         '(orderless-regexp :dispatchers first-initialism flex-if-twiddle))
 #+end_src

** Component separator regexp

The pattern components are space-separated by default: this is
controlled by the variable =orderless-component-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-component-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.

** Pattern compiler

The default mechanism for turning an input string into a list of
regexps to match against, configured using
=orderless-component-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 an optional
second argument that specifies a list to use instead of
=orderless-component-matching-styles=.

** Interactively changing the configuration

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 [[https://github.com/abo-abo/hydra][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. There are two "override" variables:

- =orderless-transient-matching-styles= which, if non-nil, overrides
  =orderless-component-matching-styles=, and
- =orderless-transient-component-separator= which, if non-nil,
  overrides =orderless-component-separator=.

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 set them to =nil= again after each completion session, use
the following configuration:

#+begin_src emacs-lisp
  (add-hook 'minibuffer-exit-hook
            #'orderless-remove-transient-configuration)
#+end_src

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

#+begin_src emacs-lisp
  (defun my/match-components-literally ()
    "Components match literally for the rest of the session."
    (interactive)
    (setq orderless-transient-matching-styles
          '(orderless-literal :dispatchers)))

  (add-hook 'minibuffer-exit-hook
            #'orderless-remove-transient-configuration)

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

Note there is nothing after =:dispatchers= in the above code. This is
different from not including =:dispatchers= at all in the value of
=orderless-transient-matching-styles=: omitting it all together means
inherit the dispatchers from =orderless-component-matching-styles=;
while including =:dispatchers= overrides the list of dispatchers ---in
the example above, setting it to the empty list.

* 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).

** Icicles's progressive matching

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 lists of candidates. In [[https://www.emacswiki.org/emacs/Icicles][Icicles]] this
is called /progressive completion/ and using =S-SPC= instead of =SPC= to
separate components will do it. (Note that Ivy has an analogous
command, also bound to =S-SPC=, called =ivy-restrict-to-matches=, so you
can get the effect of out of order matching without using
=ivy--regex-ignore-order=.)

* Integration with other completion UIs

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.

** Ivy

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

#+begin_src emacs-lisp
  (setq ivy-re-builders-alist '((t . orderless--ivy-re-builder)))
#+end_src

** Selectrum

To use =orderless= from Selectrum add this to your Selectrum
configuration:

#+begin_src emacs-lisp
  (setq selectrum-refine-candidates-function #'orderless-filter)
  (setq selectrum-highlight-candidates-function #'orderless-highlight-matches)
#+end_src