bug#50136: 28.0.50; A problem with rx-let expansion

["Mattias Engdegård" <mattiase@acm.org>]

[-- Attachment #1: Type: text/plain, Size: 537 bytes --]

23 aug. 2021 kl. 12.45 skrev Michael Heerdegen <michael_heerdegen@web.de>:

> I you find a way to get along without examples, all the better.  I
> suggested to use an example because it might be the simplest way to
> explain how things work, and because the way things work may come
> unexpected for some (like me).  But providing some more details more
> explicitly might be as good as well.

Here is my proposed change to the manual. I didn't change the doc strings since they already refer to that Info node.
Good enough?


[-- Attachment #2: 0001-Add-example-of-advanced-user-defined-Rx-form-to-manu.patch --]
[-- Type: application/octet-stream, Size: 1680 bytes --]

From cb1daffa5f226278723b4a96a698883d7010947a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mattias=20Engdeg=C3=A5rd?= <mattiase@acm.org>
Date: Mon, 23 Aug 2021 17:02:51 +0200
Subject: [PATCH] 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).
---
 doc/lispref/searching.texi | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/lispref/searching.texi b/doc/lispref/searching.texi
index 4d5ae3cb43..a0935eee2b 100644
--- a/doc/lispref/searching.texi
+++ b/doc/lispref/searching.texi
@@ -1649,6 +1649,25 @@ Extending Rx
 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.
+
+User-defined forms themselves 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{}
-- 
2.21.1 (Apple Git-122.3)