Emacs Docs

Appearance

Style dispatchers ​

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’. You can use this feature to define your own "query syntax". For example, the default value of ‘orderless-style-dispatchers’ lists a single dispatcher called ‘orderless-affix-dispatch’ which enables a simple syntax based on special characters used as either a prefix or suffix:

  • ! modifies the component with ‘orderless-not’. Both ‘!bad’ and ‘bad!’ will match strings that do not contain the pattern ‘bad’.
  • & modifies the component with ‘orderless-annotation’. The pattern will match against the candidate’s annotation (cheesy mnemonic: andnotation!).
  • , uses ‘orderless-initialism’.
  • = uses ‘orderless-literal’.
  • ^ uses ‘orderless-literal-prefix’.
  • ~ uses ‘orderless-flex’.
  • % makes the string match ignoring diacritics and similar inflections on characters (it uses the function ‘char-fold-to-regexp’ to do this).

You can add, remove or change this mapping between affix characters and matching styles by customizing the user option ‘orderless-affix-dispatch-alist’. Most users will probably find this type of customization sufficient for their query syntax needs, but for those desiring further control the rest of this section explains how to implement your own 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 of writing your own dispatchers, 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’),
  • 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 (this is part of the functionality of the default configuration).

You can achieve this with the following configuration:

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

(defun not-if-bang (pattern _index _total)
  (cond
   ((equal "!" pattern)
    #'ignore)
   ((string-prefix-p "!" pattern)
    `(orderless-not . ,(substring pattern 1)))))

(setq orderless-matching-styles '(orderless-regexp)
      orderless-style-dispatchers '(first-initialism
                                    flex-if-twiddle
                                    not-if-bang))