From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Update of pcase docs for the elisp manual Date: Sun, 24 Jan 2016 16:33:04 +0200 Message-ID: <83io2j3v4v.fsf@gnu.org> References: <87d1stznc6.fsf@web.de> <83io2k5yvg.fsf@gnu.org> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: ger.gmane.org 1453645985 12265 80.91.229.3 (24 Jan 2016 14:33:05 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 24 Jan 2016 14:33:05 +0000 (UTC) Cc: emacs-devel@gnu.org To: Stefan Monnier , Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Jan 24 15:33:00 2016 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1aNLit-0004Sn-ON for ged-emacs-devel@m.gmane.org; Sun, 24 Jan 2016 15:32:59 +0100 Original-Received: from localhost ([::1]:60654 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNLis-00025l-UV for ged-emacs-devel@m.gmane.org; Sun, 24 Jan 2016 09:32:58 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:45344) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNLif-00022K-Ct for emacs-devel@gnu.org; Sun, 24 Jan 2016 09:32:46 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNLic-0008Oe-3b for emacs-devel@gnu.org; Sun, 24 Jan 2016 09:32:45 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:42015) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNLic-0008Oa-1O; Sun, 24 Jan 2016 09:32:42 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:3896 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aNLib-0003jA-AV; Sun, 24 Jan 2016 09:32:41 -0500 In-reply-to: (message from Stefan Monnier on Sat, 23 Jan 2016 23:40:19 -0500) 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.14 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-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:198697 Archived-At: > From: Stefan Monnier > Date: Sat, 23 Jan 2016 23:40:19 -0500 > > > (pcase x > > ((and (pred numberp) > > (let (pred (lambda (x) (< 5 x))) > > (abs x))) > > The second arg to `let' (i.e. (abs x) here) is a plain old normal > expression, so it does not necessarily use the currently matched object > and if it wants to, it can do it as above by simply re-using the same > expression as was passed to `pcase'. Yes, I know. That's not the confusing part (although re-using 'x' in this way muddies the waters and doesn't help). > So (let (pred (lambda (x) (< 5 x))) (abs x)) ends up being equivalent to > (guard (< 5 (abs x))). Yes, because it doesn't use the feature for which 'let' was invented: it doesn't bind any symbols to values. And that's the confusing part: 'let' is being used where it isn't really needed, so this is not the ideal example for the 'let' pattern. > > . The exact syntax and possible forms of QPatterns are described > > ambiguously and seemingly incompletely, and profoundly contradict > > almost every given example of them. Both Michael and the previous > > manual text describe them as follows: > > > > The form is `QPAT where QPAT is one of the following: > > > > (QPAT1 . QPAT2) > > [QPAT1 QPAT2 ... QPATn] > > ,PAT > > ATOM > > > > The last two look wrong: AFAIU, there is no QPattern of the form > > `,PATH > > I think `,PAT is a valid UPattern, which is simply equivalent to PAT. > > > or `ATOM. > > And `ATOM is also a valid UPattern. The above describes QPatterns, not UPatterns. I also arrived at the conclusion that we should talk about UPatterns (see how I changed the above for the manual), but then those 2 shouldn't appear in the list as QPatterns, they should be explained as UPatterns a QPattern can use by unquoting them. Which is exactly what I did in the manual. > > The examples are terribly confusing. They all use this form: > > `(A B C D ...) > > where each of A, B, etc. can be one of: > > - ,UPAT > > - ATOM > > And yet this pattern doesn't appear at all in the possible forms > > of QPAT above! > > Of course it does: `(A B C D ...) is 100% equivalent to > `(A . (B . (C . (D . ...)))) and (QPAT1 . QPAT2) is a QPAT. Which IMO means we must add the likes of `(A B C D) to the manual, because expecting the readers of software documentation to solve riddles as they read is not a good idea. > > . Many of the examples using QPatterns seem to allow to be easily > > rewritten to use only UPatterns, by adding additional 'pred' and > > 'guard' conditions. Is that true? > > Very much so. Then this, too, should be added, probably with an example. Michael, would you mind providing an educational example for that, please? > > . Last, but not least: NEWS says we now have a new UPattern 'quote', > > but neither John, nor Michael or the doc strings mention this > > pattern. What did I miss? > > The docstring says: > > 'VAL matches if the object is ‘equal’ to VAL. > > and 'VAL is also spelled (quote VAL). This probably means that 'quote' shouldn't be documented as a separate pattern, as that is a technicality which is much more likely to confuse than to help understanding. Unless, that is, there are important scenarios where using (quote FOO) in a pattern is required where it isn't a trivial replacement for 'FOO. Do you know about such scenarios? Thanks.