doc: document @(op) and predicate operator.

1 files changed, 81 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index 29c81aa9..6fb47021 100644
--- a/txr.1
+++ b/txr.1
@@ -40095,6 +40095,87 @@ values.
     x) -> 2
 .brev
 
+.coNP Pattern operator @ op
+.synb
+.mets @(op << form +)
+.syne
+.desc
+The
+.code op
+operator uses the syntax of the
+.code op
+macro to produce an anonymous function, which is used as the basis of a
+predicate match. The function is applied to the corresponding object.
+If the function yields true, the match succeeds, otherwise it fails.
+
+The syntax and semantics of
+.code op
+is exactly that of the
+.code op
+macro.
+
+The syntax must be used in such a way that the resulting anonymous
+function is capable of being called with exactly one argument.
+
+.TP* Example
+
+.verb
+  ;; 11 matches, since it is in the 10-13 range
+  (if-match @(op <= 10 @1 13) 11 :yes :no) -> :yes
+
+  ;; let can be used to capture into a variable
+  (when-match @(let x @(op <= 10 @1 13)) 11 x) -> 11
+.brev
+
+.NP* Pattern predicate operator
+.synb
+.mets >> @( function <> [ symbol ])
+.syne
+.desc
+Whenever the operator of a pattern predicate is not recognized, that operator
+is assumed to be the name of a function, and the syntax is treated as the
+predicate operator.
+
+The pattern predicate operator invokes the function, passing it the
+corresponding object as an argument. The match is successful if the function
+returns true.
+
+Optionally, if the
+.meta symbol
+is specified, and is not
+.codn nil ,
+it is bound to the corresponding object.
+
+The
+.meta symbol
+argument, if present, must be a
+.code bindable
+symbol, or else
+.codn nil .
+
+The
+.meta function
+must be capable of accepting exactly one argument.
+
+Note: a
+.code lambda
+expression may be used as
+.metn function .
+
+.TP* Example:
+
+.verb
+  (when-match (@(evenp) @(oddp x)) '(2 3) x) -> 3
+.brev
+
+An instance of the
+.mono
+.meti >> @( operator ...)
+.onom
+syntax denotes the predicate operator whenever the
+.meta operator
+symbol is not one of the predicates.
+
 .SS* Quasiquote Operator Syntax
 .coNP Macro @ qquote
 .synb