Only enable regexp and literal matching styles by default

* Avoid performance issues with initialism when filtering long candidates (#39)
* README: Update default matching styles
* README: Document `orderless-define-completion-style`
* README: Update `without-if-bang` such that it ignores "!"

1 files changed, 31 insertions, 5 deletions

diff --git a/README.org b/README.org
index fb55289..a7aff1e 100644
--- a/README.org
+++ b/README.org
@@ -20,7 +20,7 @@ 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.
+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
@@ -150,8 +150,8 @@ define new matching styles. The predefined ones are:
   This maps =abc= to =a.*b.*c=.
 
 The variable =orderless-matching-styles= can be set to a list of the
-desired matching styles to use. By default it enables the literal,
-regexp and initialism styles.
+desired matching styles to use. By default it enables the literal and
+regexp styles.
 
 *** Style dispatchers
 
@@ -192,8 +192,11 @@ regexp and initialism styles.
      (if (= index 0) 'orderless-initialism))
 
    (defun without-if-bang (pattern _index _total)
-     (when (string-prefix-p "!" pattern)
-       `(orderless-without-literal . ,(substring pattern 1))))
+     (cond
+      ((equal "!" pattern)
+       '(orderless-literal . ""))
+      ((string-prefix-p "!" pattern)
+       `(orderless-without-literal . ,(substring pattern 1)))))
 
    (setq orderless-matching-styles '(orderless-regexp)
          orderless-style-dispatchers '(first-initialism
@@ -222,6 +225,29 @@ 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.
 
+** Defining custom orderless styles
+
+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.
+
+#+begin_src emacs-lisp
+  (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))))
+#+end_src
+
 ** Faces for component matches
 
 The portions of a candidate matching each component get highlighted in