Re: Clarify `pcase' `rx' pattern doc

[Michael Heerdegen]

Eli Zaretskii <address@hidden> writes:

> > > + [...]  If the target is not a string, signal an error.
> > 
> > We want to change that, so I think you can drop that sentence.
>
> Shouldn't it be dropped when that change is committed?

Then we would break documented behavior then.  What would be the gain?

> > But can we remove the sentence saying "Multiple occurrences of the
> > same VAR refer to the same submatch."?  It's completely redundant
> > IMHO.
>
> Is it redundant even when VAR is not a submatch number, but a symbol?

I think so.  A symbol VAR references the explicit binding created with
(let VAR ...), i.e. a submatch, just like in the number case.

> Btw, in this part:
>
> > +  (let VAR SEXP...)  creates a new explicitly numbered submatch
> > +                     that matches regular expressions SEXP, and
> > +                     binds the match to VAR.
>
> Does "explicitly numbered" mean that VAR must be a number?  If it can
> be something else, perhaps "explicitly named" is better?

AFAIK, in `let' VAR must be a symbol, but it seems the submatch is also
numbered as side effect, e.g.

(pcase "Hala"
  ((rx "H" (let x "a") (regex ".*") (backref 1)) x))
==> "a"

In `backref' the argument can be a number or a symbol VAR.  That's why I
would prefer a different argument name in the docstring, "REF" maybe.  I
had done that in my suggested patch.


Michael.