From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Michael Heerdegen Newsgroups: gmane.emacs.devel Subject: Re: The poor state of documentation of pcase like things. Date: Sun, 20 Dec 2015 14:11:26 +0100 Message-ID: <87si2xtgch.fsf@web.de> References: <20151216202605.GA3752@acm.fritz.box> <87fuyytq6b.fsf@web.de> <20151219183057.GA2238@acm.fritz.box> <871taimaqu.fsf@web.de> <20151219222551.GB1899@acm.fritz.box> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1450617111 14419 80.91.229.3 (20 Dec 2015 13:11:51 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sun, 20 Dec 2015 13:11:51 +0000 (UTC) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sun Dec 20 14:11:43 2015 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 1aAdm2-00069P-5F for ged-emacs-devel@m.gmane.org; Sun, 20 Dec 2015 14:11:42 +0100 Original-Received: from localhost ([::1]:40737 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAdm1-0004ln-5p for ged-emacs-devel@m.gmane.org; Sun, 20 Dec 2015 08:11:41 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:55041) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAdlx-0004lg-M7 for emacs-devel@gnu.org; Sun, 20 Dec 2015 08:11:38 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aAdlt-0008Rj-Jk for emacs-devel@gnu.org; Sun, 20 Dec 2015 08:11:37 -0500 Original-Received: from mout.web.de ([212.227.17.12]:64955) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAdlt-0008Rf-9k for emacs-devel@gnu.org; Sun, 20 Dec 2015 08:11:33 -0500 Original-Received: from drachen.dragon ([90.186.2.57]) by smtp.web.de (mrweb103) with ESMTPSA (Nemesis) id 0M73SD-1aMy1v2Qxp-00wqKx; Sun, 20 Dec 2015 14:11:31 +0100 In-Reply-To: <20151219222551.GB1899@acm.fritz.box> (Alan Mackenzie's message of "Sat, 19 Dec 2015 22:25:51 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-Provags-ID: V03:K0:NQ23kJjhHGRE7XKtZz8Sd6Gc0HOhklxF2W422LAW0vvuMpR7ps2 iTvW+FeIsFVspQGGAJcIgVJT/X7v+E8u1g7UsbBA6MSkoMTmWQwbxlXMN5HY/XY2YwEW9j1 R8BDqAa1nY5k1PfBa15IA1Q4L0ZLDbfTbdISDV2A16VtWKBz9Ispc5ywSiJ2fGs/yFSOAxj O8VQBqdoF2IgLynVF9b8Q== X-UI-Out-Filterresults: notjunk:1;V01:K0:aZ4bcROmJ00=:mHEY1+b0dp2M4xXVGlFy0M QrFemTtuvR2mmXkRstbfmkyZRrwi+TKasSpSoGZ/zlmtkoQqsgbHiOWwvmWu42mzA93AQb8Us 3xd8J1W4OXQk+YO2/+uwhUca6JZUSeP1IX5wZ49jaXC0XCMELzBYIVAiRL3yJiybgvzZTzNie YBfjHyv8C8tDg3JiNEx4t6Xj0PKrWMsb76GjXNzpA46QWKJDa7k6cDH4wWNDo3+50Zn0Mf+o2 XgMwfRk+hnCCB8VLxq9sb8J06c5PP9RAJ0C3EgrHILHG0EDWvip3fnXaPKKJA+ySy03rq6eKq gNqD7AuexWw7cGdArlj7EB053ZcHQUUE6gUM3z9CWr2HC2+swhhsNYsh7Wg5vi3K7TfEXxnJ2 kvU/QArBiM1V+9zo7OA72yVfmiBXU5mZJ3W3Bs2rt6xEpJNiY/IJLvDfN3VdAT8Hz9TzpWcX4 jCm+bXE5up3qUiyQ8N77CfWWyOL1mqxK4iKifTS46H2e+yWU4lqsdC97KPVZ7irQC8gVeWQ6o gGdtDeHjTSOAdS2lqgqaGifHb2TiOB0g2TgFv4bsdqN+1Rce7fxGPfeK0ASVBBlmthYlMYMgO YzYppCUpMRLplHwrq1sdqLliMpVIHF9mD3LkEBpNlJOqDD/6xGqXlHNXyFO+tCpAE26BLgl5E 0+BEwLHbfQfv8j6kfw27bU7810DTk/mfmBJlr3iQsx5ZpnMI7t962baRoElTyCV6CC9xhtNlM sfBkQjVv3UvIxnWApJ7eqrxvPdpGjKMsA8UNDNxw7H74JEZGVsk4MBaXgn96a7uwQLsbY43Z X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.12 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:196548 Archived-At: Alan Mackenzie writes: > I don't really know what pcase-let does. I haven't a clue what > pcase-lambda, pcase-defmacro, ... do. The doc of `pcase-defmacro' is very terse, but I find the docs of=20 `pcase-lambda' and `pcase-let' understandable. What's wrong with these? > > Mmh, but it also doesn't say that the normal meanings of and, or, ' and > > let are suspended. > > I think it doesn't have to, because a pcase pattern is not an > > expression that is evaluated, so symbols with known names can't have > > the same semantics as a pattern than as a defined function. > > That would be a good argument if only experts read the doc string. > Thoroughly confused people also read doc strings. I don't think we > should presuppose such sophisticated discernment in the typical > reader. Ok, speaking it out is a good idea. But I would prefer the (improved) manual section. > > > There is still no explicit statement of what pcase's ` and , mean. > > > But do we agree that the current docstring completely explains the > > semantics, even if the definition is recursive? > > I don't agree. Completely missing is something like "pcase compares the > value with each pattern in turn until one matches, and it then evaluates > the corresponding BODY, returning the result of the last body form > evaluated. If no pattern matches, nil is returned.". The somewhat > offensive "perform ML-style pattern matching on that value" is no > substitute for this. I agree, but that is unrelated to backquote. > There is no mention of ``' and `,' in the section on patterns. Or is > \\=3D'VAL really meant to be \\=3D`VAL? No. Since it's defined with `pcase-defmacro' now, it's listed later in the section describing all additional pattern types: ,---------------------------------------------------------------------- | -- `QPAT |=20 | Backquote-style pcase patterns. | QPAT can take the following forms: | (QPAT1 . QPAT2) matches if QPAT1 matches the car and QPAT2 the cd= r. | [QPAT1 QPAT2..QPATn] matches a vector of length n and QPAT1..QPATn mat= ch | its 0..(n-1)th elements, respectively. | ,PAT matches if the pcase pattern PAT matches. | ATOM matches if the object is =E2=80=98equal=E2=80=99 = to ATOM. | ATOM can be a symbol, an integer, or a | string. `---------------------------------------------------------------------- Did you miss it all the time? > But what does ``' _do_? What it normally does is well explained in its > own doc string (which will need modification for pcase). No, pcase just uses the symbol ``'. What ``' "means" in pcase doesn't belong in the docstring of `backquote', those are two completely unrelated things, there is just some analogy (which led Stefan to use a backquote for the syntax). > Are you saying that "QPattern" has no more conceptual meaning than > "patterns which are backquoted"? That's were the name comes from. But the forms a QPAT can have are different from the "normal" pcase pattern types. See the -- `QPAT section I quoted. Regards, Michael. P.S. I'll be on a trip for the next two days in ~ two hours and will not be able to read this list in that time.