[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Clarify `pcase' `rx' pattern doc
From: |
Michael Heerdegen |
Subject: |
Re: Clarify `pcase' `rx' pattern doc |
Date: |
Mon, 18 Jun 2018 19:22:01 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
Eli Zaretskii <address@hidden> writes:
> > (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.
>
> I don't like calling this "regexp". Elsewhere in rx documentation we
> say either "regexps in sexp form" or just "form". Using "regexp"
> might confuse the reader to think these are the "normal" regexp
> strings.
Wound "rx-form" be acceptable? Also see below.
> > +`string-match'. An error is raised if the target is not a string.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Please avoid the passive tense.
I've dropped that sentence after Stefan's comment.
> > - (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.
>
> IMO, this change is for the worse: the original clearly indicated that
> FORM is the rx-style regexp, whereas the new text blurs this
> indication.
The problem here: we usually call an expression (something to be
evaluated) a FORM. And we have a `let' pattern in `pcase', and its
second argument is really a form. This is super confusing and the main
reason why I didn't understand how `let' and `backref' work in this
pattern after reading the sources. So again: is something like
"RX-FORM" acceptable, or something similar?
> > + (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.
>
> I'd use just REF here instead of VAR-OR-NBR, which is quite a
> mouthful, and doesn't help in understanding the semantics until one
> reads the explanation.
Ok, I'll do this.
Thanks,
Michael.
Re: Clarify `pcase' `rx' pattern doc, Michael Heerdegen, 2018/06/18
- Re: Clarify `pcase' `rx' pattern doc, Stefan Monnier, 2018/06/18
- Re: Clarify `pcase' `rx' pattern doc, Eli Zaretskii, 2018/06/18
- Re: Clarify `pcase' `rx' pattern doc, Michael Heerdegen, 2018/06/21
- Re: Clarify `pcase' `rx' pattern doc, Eli Zaretskii, 2018/06/21
- Re: Clarify `pcase' `rx' pattern doc, Michael Heerdegen, 2018/06/21
- Re: Clarify `pcase' `rx' pattern doc, Eli Zaretskii, 2018/06/23