From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31311: 27.0; doc of `pcase' Date: Sun, 29 Apr 2018 19:47:08 -0700 (PDT) Message-ID: References: <87vac9k04a.fsf@web.de> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1525056376 24324 195.159.176.226 (30 Apr 2018 02:46:16 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 30 Apr 2018 02:46:16 +0000 (UTC) Cc: 31311@debbugs.gnu.org To: Michael Heerdegen Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Mon Apr 30 04:46:12 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1fCypP-00067w-Px for geb-bug-gnu-emacs@m.gmane.org; Mon, 30 Apr 2018 04:46:12 +0200 Original-Received: from localhost ([::1]:57579 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCyrR-0003V1-Ej for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 22:48:17 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:48044) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCyrH-0003Uv-OM for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 22:48:09 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fCyrC-00072a-QY for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 22:48:07 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35425) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fCyrC-00072S-Kw for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 22:48:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fCyrC-0000Uz-B2 for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 22:48:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Mon, 30 Apr 2018 02:48:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 31311 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 31311-submit@debbugs.gnu.org id=B31311.15250564411858 (code B ref 31311); Mon, 30 Apr 2018 02:48:02 +0000 Original-Received: (at 31311) by debbugs.gnu.org; 30 Apr 2018 02:47:21 +0000 Original-Received: from localhost ([127.0.0.1]:43322 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCyqW-0000Ts-MK for submit@debbugs.gnu.org; Sun, 29 Apr 2018 22:47:20 -0400 Original-Received: from userp2120.oracle.com ([156.151.31.85]:46684) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fCyqU-0000Tg-TA for 31311@debbugs.gnu.org; Sun, 29 Apr 2018 22:47:19 -0400 Original-Received: from pps.filterd (userp2120.oracle.com [127.0.0.1]) by userp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w3U2koT5011313; Mon, 30 Apr 2018 02:47:12 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : cc : subject : references : in-reply-to : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=0Q0x7hA/RWVblFHV/uNzj/Axap0AZTqlTExnRmTLkvw=; b=Zrmzlgyxj2VIOsJemLWnuGWAxH7Rp2NSU4YV6anxLMXbdoMO4FC32jRPPfj0dG5lqB2n acUMmRwlyxz5xHfhMVMwdGu/IUqzk3DaDmtoxVq00hExK7Oh55RmV5WQiaZ2sR9F4Tvq bWRC4brgAjNA2Qy2tD2fNTvJIrXlY12cf3GGLavSe/JHDB/IeIx0fLRnVGN113CYUoSy ZqsOFCikfzmrMaaVtV6p9gtyP7HTLGR5VLUBROgpj2u6hFJN50lNChmgRskqjhznjdrs 5sWTHRUXD59xTB6fvcbHXPKWtZZkM9dcV696QLOuBMOHaBnJ1ReTZv09yGhHmkcnhbxN ng== Original-Received: from userv0021.oracle.com (userv0021.oracle.com [156.151.31.71]) by userp2120.oracle.com with ESMTP id 2hmhmfabmy-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 30 Apr 2018 02:47:12 +0000 Original-Received: from aserv0121.oracle.com (aserv0121.oracle.com [141.146.126.235]) by userv0021.oracle.com (8.14.4/8.14.4) with ESMTP id w3U2lBW8025169 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 30 Apr 2018 02:47:12 GMT Original-Received: from abhmp0001.oracle.com (abhmp0001.oracle.com [141.146.116.7]) by aserv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w3U2lAta023451; Mon, 30 Apr 2018 02:47:11 GMT In-Reply-To: <87vac9k04a.fsf@web.de> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4678.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8878 signatures=668698 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=0 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1804300026 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:145852 Archived-At: Hi Michael, > I've read the docstring again. There are indeed many things left > unclear. I think a prior version already had been clearer, though, much > also more brief. If it was both clearer and more brief, let's consider resurrecting it. ;-) > > 2. Don't use ATOM unless you mean any atom, even if you explain > > subsequently that you really mean a self-evaluating atom. >=20 > The best part of the doc string is the "complete list of patterns". > What is says is right: "ATOM can be a keyword, an integer, or a string". > In particular, floats are excluded. nil and t are also excluded. > "KEYWORD-OR-INTEGER-OR-STRING" is not a good name, however. It may not be a good name, but it is not so misleading. And it's not used in a zillion places, so it's not a big deal if the name is long: INTEGER-STRING-OR-KEYWORD or even perhaps INTEGER|STRING|KEYWORD. We have much longer stuff in the description of font-lock stuff and elsewhere. Complex things need careful breakdowns and named parts. "Atom", without that qualification, includes lots of other things, including vectors and, in particular, symbols. Maybe it should say something about _why_ keywords, integers, and strings are allowed here, but not vectors (since strings are OK) or other numbers. What is it about those 3 types that make them special in this regard? Oh, and do the other two occurrences of ATOM - those in the description of Q-patterns - mean the same thing: keyword, string, or integer? Nothing said about that; not clear. A user really does seem better off, in the case of this feature, reading the source code and ignoring the doc. The doc confuses more than helps. It raises more questions that it answers, I think. > > 3. The doc string (but not the Elisp manual, node `Pattern matching > case > > statement') refers to "the object" without ever specifying what it > > is. This makes all of the specifications that use "the object" > > meaningless: 'VAL, (pred FUN), and (app FUN PAT). > > > > The manual uses "the value being matched" instead, which is OK > > (understandable). >=20 > Yes, that's what I would prefer. >=20 > > Still, it would be clearer to give a name to "the value being > > matched" at the beginning: EXPVAL, for example, at the place where > > you say, "based on the value of the expression". >=20 > That's not necessarily true, however. For example, in > (pcase .9 ((let (pred integerp) 1) t)) > (which evals to t) "(pred integerp)" is matched against 1, not the > original expression (which is ignored by the pattern in this case). Then such exceptions need to be pointed out. Just saying (over and over, BTW) "the value being matched", let alone "the object", does not make that clear. There is not a good, comprehensive presentation of just what _matching_ involves, it seems. And that's the _whole point_ of something like `pcase': what it's matching does; how it works. If a user can't get a good mental model of this feature from reading the doc then the doc hasn't done its job. The behavior of such a `let' pattern is not obvious, even with the mini-example presented. As a first approximation, and as the overall description and name, EXPVAL is OK, I think, as is "the value of EXPRESSION". The first paragraph makes it clear, even if it is not 100% true, that each PATTERN describes EXPRESSION's value in some sense (typically its structure). We have to have some basis for talking about the parts and pieces. Especially when things are complicated is it helpful or necessary to name things and be precise about which ones we're talking about. > > 5. Don't use "QPattern" and "UPattern". Use "Q pattern" and "U > > pattern", or (probably better) "Q-pattern" and "U-pattern". >=20 > I would rather like to get rid from these old names completely. OK. What new names would you propose? But I think I agree with you. Seems like just PATTERN would make sense where we use both QPATTERN and UPATTERN. The backquote char is anyway not part of a QPATTERN; it precedes it. Which points to another thing that's not clear: the description, under QPATTERN of ",UPATTERN": "Matches if the corresponding element of the value being matched matches the specified UPATTERN." Once again we're lost. What on earth is "the _corresponding element_ of the value being matched"? What are the elements of the value being matched, and how does one of them correspond to a ",UPATTERN"? > > 6. This part of the description of `guard' is unclear, to me: > > > > For example ... and let-binds the variable 'x' to that number. > > > > I see nothing in the descriptions of `guard' and `and' that > > indicates why `x' would be let-bound in this example. >=20 > It's just the SYMBOL case: "SYMBOL matches anything and binds it to > SYMBOL." And "(and PAT...) matches if all the patterns match." OK. So x is bound to the value of EXPRESSION, and the whole pattern matches if x is non-nil and < 10. Wouldn't it be better as something like this? (and x (guard (and (numberp x) (< x 10)))) The description says that (and x (guard (< x 10))) matches any number smaller than 10. But what happens if what x matches and is thus bound to is not a number at all? In fact, that's another thing that's unclear to me. What happens during "matching" that would normally raise an error? Matching involves some kind of comparison (even unification matching does). What happens when things that get compared during matching are incomparable? Then, the following sentence seems not always to hold or, rather, it seems meaningless. How can an _occurrence_ of a symbol become an eq test? "If a SYMBOL is used twice in the same pattern the second occurrence becomes an 'eq'uality test." That doc-string statement is missing from the manual, AFAICT. What is it really trying to say? Where's the eq test in this: (and x (guard (< x 10)))? I almost feel like the more closely I read this doc the less clear it gets. I'm serious when I say that it seems like a blog about using `pcase' would be helpful. But that wouldn't obviate coming up with clear and complete doc for the manual, and clear doc for the doc string.