From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Clarify `pcase' `rx' pattern doc Date: Mon, 18 Jun 2018 19:56:06 +0300 Message-ID: <83wouwrq3d.fsf@gnu.org> References: <87fu1rqr6m.fsf@web.de> <87in6gff2t.fsf@web.de> Reply-To: Eli Zaretskii NNTP-Posting-Host: blaine.gmane.org X-Trace: blaine.gmane.org 1529342333 26262 195.159.176.226 (18 Jun 2018 17:18:53 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 18 Jun 2018 17:18:53 +0000 (UTC) Cc: emacs-devel@gnu.org To: Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jun 18 19:18:49 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fUxne-0006Sg-Lf for ged-emacs-devel@m.gmane.org; Mon, 18 Jun 2018 19:18:42 +0200 Original-Received: from localhost ([::1]:36146 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUxpj-0005OV-Tp for ged-emacs-devel@m.gmane.org; Mon, 18 Jun 2018 13:20:51 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:54732) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUxRs-0004d4-7C for emacs-devel@gnu.org; Mon, 18 Jun 2018 12:56:13 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fUxRn-0004ez-8x for emacs-devel@gnu.org; Mon, 18 Jun 2018 12:56:12 -0400 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:42169) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fUxRn-0004el-4w; Mon, 18 Jun 2018 12:56:07 -0400 Original-Received: from [176.228.60.248] (port=4732 helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256) (Exim 4.82) (envelope-from ) id 1fUxRm-0004qc-Ku; Mon, 18 Jun 2018 12:56:07 -0400 In-reply-to: <87in6gff2t.fsf@web.de> (message from Michael Heerdegen on Mon, 18 Jun 2018 14:34:50 +0200) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Original-Sender: "Emacs-devel" Xref: news.gmane.org gmane.emacs.devel:226465 Archived-At: > From: Michael Heerdegen > Cc: Eli Zaretskii > Date: Mon, 18 Jun 2018 14:34:50 +0200 > > > 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, I have a few minor comments regarding the style: > (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. > +`string-match'. An error is raised if the target is not a string. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Please avoid the passive tense. In this case, I'd rephrase: If the target is not a string, this macro signals an error. > - (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. > + (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. This is OK for the emacs-26 branch, once we agree on the above nits.