[elpa] externals/orderless 8d187bd31e 171/204: Only enable regexp and literal matching styles by default

[ELPA Syncer]

branch: externals/orderless
commit 8d187bd31e44e7e46fb1c3158c31c4a38e223618
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>

    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 "!"
---
 README.org     | 36 +++++++++++++++++++++++++++++++-----
 orderless.el   |  4 ++--
 orderless.texi | 39 ++++++++++++++++++++++++++++++++++-----
 3 files changed, 67 insertions(+), 12 deletions(-)

diff --git a/README.org b/README.org
index fb55289e9b..a7aff1e399 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
diff --git a/orderless.el b/orderless.el
index d21bebd573..c67e68574f 100644
--- a/orderless.el
+++ b/orderless.el
@@ -48,7 +48,7 @@
 ;; from strings to strings that map a component to a regexp to match
 ;; against.  The variable `orderless-matching-styles' lists the
 ;; matching styles to be used for components, by default it allows
-;; literal, regexp and initialism matching.
+;; literal and regexp matching.
 
 ;;; Code:
 
@@ -114,7 +114,7 @@ value means highlighting is skipped."
   :type '(choice boolean function))
 
 (defcustom orderless-matching-styles
-  '(orderless-literal orderless-regexp orderless-initialism)
+  '(orderless-literal orderless-regexp)
   "List of component matching styles.
 If this variable is nil, regexp matching is assumed.
 
diff --git a/orderless.texi b/orderless.texi
index eb3dc23731..c26060e6a2 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -36,6 +36,7 @@ Customization
 
 * Component matching styles::
 * Component separator regexp::
+* Defining custom orderless styles::
 * Faces for component matches::
 * Pattern compiler::
 * Interactively changing the configuration::
@@ -67,7 +68,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
@@ -112,6 +113,7 @@ Bug reports are highly welcome and appreciated!
 @menu
 * Component matching styles::
 * Component separator regexp::
+* Defining custom orderless styles::
 * Faces for component matches::
 * Pattern compiler::
 * Interactively changing the configuration::
@@ -189,8 +191,8 @@ This maps @samp{abc} to @samp{a.*b.*c}.
 @end table
 
 The variable @samp{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.
 
 @menu
 * Style dispatchers::
@@ -242,8 +244,11 @@ You can achieve this with the following configuration:
   (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
@@ -273,6 +278,30 @@ If you are implementing a command for which you know you 
want a
 different separator for the components, bind
 @samp{orderless-component-separator} in a @samp{let} form.
 
+@node Defining custom orderless styles
+@section Defining custom orderless styles
+
+Orderless allows the definition of custom completion styles using the
+@code{orderless-define-completion-style} macro. Any Orderless configuration
+variable can be adjusted locally for the new style, e.g.,
+@code{orderless-matching-styles}.
+
+By default Orderless only enables the regexp and literal matching
+styles. In the following example an @code{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.
+
+@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 lisp
+
 @node Faces for component matches
 @section Faces for component matches