Re: Clarify `pcase' `rx' pattern doc

[Michael Heerdegen]

Michael Heerdegen <address@hidden> writes:

> Opinions?

For now, I would like to install the following, slightly modified
version (I left the first sentence unchanged so that we can care about
that systematically in a later commit) into emacs-26.  Is that ok?


Thanks,

Michael.

>From c03375d0e086c3bc729f9a8b22eccd88804b6548 Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <address@hidden>
Date: Wed, 13 Jun 2018 01:42:34 +0200
Subject: [PATCH] Tweak 'pcase' 'rx' pattern documentation

* lisp/emacs-lisp/rx.el (rx): Improve pattern docstring.
---
 lisp/emacs-lisp/rx.el | 25 +++++++++++++------------
 1 file changed, 13 insertions(+), 12 deletions(-)

diff --git a/lisp/emacs-lisp/rx.el b/lisp/emacs-lisp/rx.el
index 85e74f28ef..6c01536380 100644
--- a/lisp/emacs-lisp/rx.el
+++ b/lisp/emacs-lisp/rx.el
@@ -1183,24 +1183,25 @@ rx
 
 
 (pcase-defmacro rx (&rest regexps)
-  "Build a `pcase' pattern matching `rx' regexps.
-The REGEXPS are interpreted as by `rx'.  The pattern matches if
-the regular expression so constructed matches EXPVAL, as if
-by `string-match'.
+  "Build a `pcase' pattern matching with `rx' REGEXPS.
+The REGEXPS are interpreted as by `rx'.  The pattern matches any
+string matched by the regular expression so constructed, as if by
+`string-match'.  An error is raised if the target is not a string.
 
 In addition to the usual `rx' constructs, REGEXPS can contain the
 following constructs:
 
-  (let VAR FORM...)  creates a new explicitly numbered submatch
-                     that matches FORM and binds the match to
-                     VAR.
-  (backref VAR)      creates a backreference to the submatch
-                     introduced by a previous (let VAR ...)
-                     construct.
+  (let VAR REGEXPS...)  creates a new explicitly numbered
+                        submatch that matches the `rx' REGEXPS
+                        and binds the match to VAR.
+  (backref VAR-OR-NBR)  creates a backreference to the submatch
+                        introduced by a previous (let VAR ...)
+                        construct; VAR-OR-NBR is either a symbol
+                        VAR or a submatch number.  It matches the
+                        exact previous submatch.
 
 The VARs are associated with explicitly numbered submatches
-starting from 1.  Multiple occurrences of the same VAR refer to
-the same submatch.
+starting from 1.
 
 If a case matches, the match data is modified as usual so you can
 use it in the case body, but you still have to pass the correct
-- 
2.17.1