README: Add section for style modifiers

2 files changed, 75 insertions, 37 deletions

diff --git a/README.org b/README.org
index e4f02f7..1050fe9 100644
--- a/README.org
+++ b/README.org
@@ -119,10 +119,11 @@ Protesilaos Stavrou's lovely [[https://gitlab.com/protesilaos/modus-themes][modu
 ** 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 regexps,
-so it is easy to define new matching styles. The regexp returned by a
-matching style can be either a string or an s-expression in =rx= syntax.
-The predefined matching styles are:
+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.
@@ -132,14 +133,6 @@ The predefined matching styles are:
 - orderless-literal :: the component is treated as a literal string
   that must occur in the candidate.
 
-- *orderless-without-literal* :: the component is a treated as a literal
-  string that must *not* occur in the candidate.
-
-  Note that nothing is highlighted for this matching style. You
-  probably don't want to use this style directly in
-  =orderless-matching-styles= but with a style dispatcher instead. There
-  is an example in the section on style dispatchers.
-
 - 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.
@@ -158,10 +151,31 @@ The predefined matching styles are:
 
   This maps =abc= to =a.*b.*c=.
 
+- *orderless-without-literal* :: the component is a treated as a literal
+  string that must *not* occur in the candidate.
+
+  Nothing is highlighted by this style. This style should not be used
+  directly in =orderless-matching-styles= but with a style dispatcher
+  instead. See also the more general style modifier =orderless-not=.
+
 The variable =orderless-matching-styles= can be set to a list of the
 desired matching styles to use. By default it enables the literal and
 regexp styles.
 
+*** Style modifiers
+
+Style modifiers are functions which take a predicate function and a
+regular expression as a string and return a new predicate function.
+Style modifiers should not be used directly in
+=orderless-matching-styles= but with a style dispatcher instead.
+
+- orderless-annotation :: this style modifier matches the pattern
+  against the annotation string of the candidate, instead of against
+  the candidate string.
+
+- orderless-not :: this style modifier inverts the pattern, such that
+  candidates pass which do not match the pattern.
+
 *** Style dispatchers
 
  For more fine-grained control on which matching styles to use for
@@ -172,9 +186,10 @@ regexp styles.
  =orderless-affix-dispatch= which enables a simple syntax based on
  special characters used as either a prefix or suffix:
 
- - =!= makes the rest of the component match using
-   =orderless-without-literal=, that is, both =!bad= and =bad!= will match
-   strings that do /not/ contain the substring =bad=.
+ - =!= 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 annotation.
  - =,= uses =orderless-initialism=.
  - === uses =orderless-literal=.
  - =~= uses =orderless-flex=.
@@ -223,17 +238,17 @@ regexp styles.
    (defun first-initialism (pattern index _total)
      (if (= index 0) 'orderless-initialism))
 
-   (defun without-if-bang (pattern _index _total)
+   (defun not-if-bang (pattern _index _total)
      (cond
       ((equal "!" pattern)
        '(orderless-literal . ""))
       ((string-prefix-p "!" pattern)
-       `(orderless-without-literal . ,(substring pattern 1)))))
+       `(orderless-not . ,(substring pattern 1)))))
 
    (setq orderless-matching-styles '(orderless-regexp)
          orderless-style-dispatchers '(first-initialism
                                        flex-if-twiddle
-                                       without-if-bang))
+                                       not-if-bang))
  #+end_src
 
 ** Component separator regexp
diff --git a/orderless.texi b/orderless.texi
index 6586e05..44747a5 100644
--- a/orderless.texi
+++ b/orderless.texi
@@ -44,6 +44,7 @@ Customization
 
 Component matching styles
 
+* Style modifiers::
 * Style dispatchers::
 
 Integration with other completion UIs
@@ -151,10 +152,11 @@ Bug reports are highly welcome and appreciated!
 @section 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 regexps,
-so it is easy to define new matching styles. The regexp returned by a
-matching style can be either a string or an s-expression in @samp{rx} syntax.
-The predefined matching styles are:
+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 @samp{rx} syntax or a predicate function. The predefined
+matching styles are:
 
 @table @asis
 @item orderless-regexp
@@ -167,15 +169,6 @@ If the component is not a valid regexp, it is ignored.
 the component is treated as a literal string
 that must occur in the candidate.
 
-@item @strong{orderless-without-literal}
-the component is a treated as a literal
-string that must @strong{not} occur in the candidate.
-
-Note that nothing is highlighted for this matching style. You
-probably don't want to use this style directly in
-@samp{orderless-matching-styles} but with a style dispatcher instead. There
-is an example in the section on style dispatchers.
-
 @item orderless-prefixes
 the component is split at word endings and
 each piece must match at a word boundary in the candidate, occurring
@@ -196,6 +189,14 @@ the characters of the component should appear in
 that order in the candidate, but not necessarily consecutively.
 
 This maps @samp{abc} to @samp{a.*b.*c}.
+
+@item @strong{orderless-without-literal}
+the component is a treated as a literal
+string that must @strong{not} occur in the candidate.
+
+Nothing is highlighted by this style. This style should not be used
+directly in @samp{orderless-matching-styles} but with a style dispatcher
+instead. See also the more general style modifier @samp{orderless-not}.
 @end table
 
 The variable @samp{orderless-matching-styles} can be set to a list of the
@@ -203,9 +204,29 @@ desired matching styles to use. By default it enables the literal and
 regexp styles.
 
 @menu
+* Style modifiers::
 * Style dispatchers::
 @end menu
 
+@node Style modifiers
+@subsection Style modifiers
+
+Style modifiers are functions which take a predicate function and a
+regular expression as a string and return a new predicate function.
+Style modifiers should not be used directly in
+@samp{orderless-matching-styles} but with a style dispatcher instead.
+
+@table @asis
+@item orderless-annotation
+this style modifier matches the pattern
+against the annotation string of the candidate, instead of against
+the candidate string.
+
+@item orderless-not
+this style modifier inverts the pattern, such that
+candidates pass which do not match the pattern.
+@end table
+
 @node Style dispatchers
 @subsection Style dispatchers
 
@@ -219,9 +240,11 @@ special characters used as either a prefix or suffix:
 
 @itemize
 @item
-@samp{!} makes the rest of the component match using
-@samp{orderless-without-literal}, that is, both @samp{!bad} and @samp{bad!} will match
-strings that do @emph{not} contain the substring @samp{bad}.
+@samp{!} modifies the component with @samp{orderless-not}. Both @samp{!bad} and @samp{bad!}
+will match strings that do @emph{not} contain the pattern @samp{bad}.
+@item
+@samp{@@} modifies the component with @samp{orderless-annotation}. The pattern
+will match against the candidate annotation.
 @item
 @samp{,} uses @samp{orderless-initialism}.
 @item
@@ -281,17 +304,17 @@ You can achieve this with the following configuration:
 (defun first-initialism (pattern index _total)
   (if (= index 0) 'orderless-initialism))
 
-(defun without-if-bang (pattern _index _total)
+(defun not-if-bang (pattern _index _total)
   (cond
    ((equal "!" pattern)
     '(orderless-literal . ""))
    ((string-prefix-p "!" pattern)
-    `(orderless-without-literal . ,(substring pattern 1)))))
+    `(orderless-not . ,(substring pattern 1)))))
 
 (setq orderless-matching-styles '(orderless-regexp)
       orderless-style-dispatchers '(first-initialism
                                     flex-if-twiddle
-                                    without-if-bang))
+                                    not-if-bang))
 @end lisp
 
 @node Component separator regexp