Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/oantolin/orderless

Emacs completion style that matches multiple regexps in any order
https://github.com/oantolin/orderless

Last synced: 12 days ago
JSON representation

Emacs completion style that matches multiple regexps in any order

Awesome Lists containing this project

README 

        
#+TITLE: Orderless

#+OPTIONS: d:nil

#+EXPORT_FILE_NAME: orderless.texi

#+TEXINFO_DIR_CATEGORY: Emacs misc features

#+TEXINFO_DIR_TITLE: Orderless: (orderless).

#+TEXINFO_DIR_DESC: Completion style for matching regexps in any order



#+html: GNU ELPA

#+html: GNU-devel ELPA

#+html: MELPA

#+html: MELPA Stable



* 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

literal 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), with the built-in Icomplete package (which is similar

to the more well-known Ido Mode), the icomplete-vertical variant from

Emacs 28 (see the external [[https://github.com/oantolin/icomplete-vertical][icomplete-vertical]] package to get that

functionality on earlier versions of Emacs), or with some third party

minibuffer completion frameworks such as [[https://gitlab.com/protesilaos/mct][Mct]] or [[https://github.com/minad/vertico][Vertico]].



All the completion UIs just mentioned are for minibuffer completion,

used when Emacs commands prompt the user in the minibuffer for some

input, but there is also completion at point in normal buffers,

typically used for identifiers in programming languages. Completion

styles can also be used for that purpose by completion at point UIs

such as [[https://github.com/minad/corfu][Corfu]], [[https://company-mode.github.io/][Company]] or the function =consult-completion-in-region=

from [[https://github.com/minad/consult][Consult]].



To use a completion style with any of the above mentioned completion

UIs simply add it as an entry in the variables =completion-styles= and

=completion-category-overrides= and =completion-category-defaults= (see

their documentation).



The =completion-category-defaults= variable serves as a default value

for =completion-category-overrides=. If you want to use =orderless=

exclusively, set both variables to =nil=, but be aware that

=completion-category-defaults= is modified by packages at load time.



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]] (see

below). Also, while Company does support completion styles directly,

pressing =SPC= takes you out of completion, so comfortably using

=orderless= with it takes a bit of configuration (see below).



If you use ELPA or MELPA, the easiest way to install =orderless= is via

=package-install=. If you use =use-package=, you can use:



#+begin_src emacs-lisp

  (use-package orderless

    :ensure t

    :custom

    (completion-styles '(orderless basic))

    (completion-category-overrides '((file (styles basic partial-completion)))))

#+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 basic)

        completion-category-overrides '((file (styles basic partial-completion))))

#+end_src



The =basic= completion style is specified as fallback in addition to

=orderless= in order to ensure that completion commands which rely on

dynamic completion tables, e.g., ~completion-table-dynamic~ or

~completion-table-in-turn~, work correctly. Furthermore the =basic=

completion style needs to be tried /first/ (not as a fallback) for TRAMP

hostname completion to work. In order to achieve that, we add an entry

for the =file= completion category in the =completion-category-overrides=

variable. In addition, the =partial-completion= style allows you to use

wildcards for file completion and partial paths, e.g., ~/u/s/l~ for

~/usr/share/local~.



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]]

- [[#integration-with-other-completion-uis][Integration with other completion UIs]]

  - [[#ivy][Ivy]]

  - [[#company][Company]]

- [[#related-packages][Related packages]]

  - [[#ivy-and-helm][Ivy and Helm]]

  - [[#prescient][Prescient]]

  - [[#restricting-to-current-matches-in-icicles-ido-and-ivy][Restricting to current matches: Icicles, Ido and Ivy]]

:END:



** Screenshot :noexport:



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



[[https://github.com/oantolin/orderless/blob/dispatcher/images/describe-function-eis-ff.png?raw=true]]



* Customization



** Component matching styles



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