Add example of advanced user-defined Rx form to manual

* doc/lispref/searching.texi (Extending Rx): Add example illustrating
how to define a user-defined Rx form that performs computation,
from a discussion with Michael Herdeegen (bug#50136).
* lisp/emacs-lisp/rx.el (rx): Clarify evaluation time for `eval`.

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 4d5ae3cb4374a1dd0bf5c9dd89d66d4414e2bd1b..68061f0b09f40ebddd6d2f8aa84cd6aae1bc2bf0 100644 (file)
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1649,6 +1649,24 @@ extra actual argument values not matched by any other parameter in
 Since the definition is global, it is recommended to give @var{name} a
 package prefix to avoid name clashes with definitions elsewhere, as is
 usual when naming non-local variables and functions.
+
+Forms defined this way only perform simple template substitution.
+For arbitrary computations, use them together with with the @code{rx}
+forms @code{eval}, @code{regexp} or @code{literal}.  Example:
+
+@example
+@group
+(defun n-tuple-rx (n element)
+  `(seq "<"
+        (group-n 1 ,element)
+        ,@@(mapcar (lambda (i) `(seq ?, (group-n ,i ,element)))
+                  (number-sequence 2 n))
+        ">"))
+(rx-define n-tuple (n element) (eval (n-tuple-rx n 'element)))
+(rx (n-tuple 3 (+ (in "0-9"))))
+  @result{} "<\\(?1:[0-9]+\\),\\(?2:[0-9]+\\),\\(?3:[0-9]+\\)>"
+@end group
+@end example
 @end defmac
 
 @defmac rx-let (bindings@dots{}) body@dots{}

diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
index 071d390f0e4e9fbc03c6732824384e54615d34fa..c48052dee9ed223797cd2951c4b12bf43c0628f2 100644 (file)
--- a/lisp/emacs-lisp/rx.el
+++ b/lisp/emacs-lisp/rx.el
@@ -1266,7 +1266,8 @@ Zero-width assertions: these all match the empty string in specific places.
 
 (literal EXPR) Match the literal string from evaluating EXPR at run time.
 (regexp EXPR)  Match the string regexp from evaluating EXPR at run time.
-(eval EXPR)    Match the rx sexp from evaluating EXPR at compile time.
+(eval EXPR)    Match the rx sexp from evaluating EXPR at macro-expansion
+                (compile) time.
 
 Additional constructs can be defined using `rx-define' and `rx-let',
 which see.