From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Alan Mackenzie Newsgroups: gmane.emacs.devel Subject: Re: Replace trivial pcase occurrences in the Emacs sources Date: Tue, 30 Oct 2018 18:09:41 +0000 Message-ID: <20181030180941.GA5705@ACM> References: <86mur137n8.fsf@gmail.com> <20181029130132.GB4195@ACM> <20181029134722.GC4195@ACM> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: blaine.gmane.org 1540922895 21728 195.159.176.226 (30 Oct 2018 18:08:15 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Tue, 30 Oct 2018 18:08:15 +0000 (UTC) User-Agent: Mutt/1.10.1 (2018-07-13) Cc: emacs-devel@gnu.org To: Stefan Monnier Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Tue Oct 30 19:08:11 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 1gHYR0-0005WC-Mb for ged-emacs-devel@m.gmane.org; Tue, 30 Oct 2018 19:08:10 +0100 Original-Received: from localhost ([::1]:54877 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gHYT6-0002f7-Hk for ged-emacs-devel@m.gmane.org; Tue, 30 Oct 2018 14:10:20 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:37975) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gHYSs-0002cs-Kv for emacs-devel@gnu.org; Tue, 30 Oct 2018 14:10:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gHYSp-0000dl-4z for emacs-devel@gnu.org; Tue, 30 Oct 2018 14:10:06 -0400 Original-Received: from colin.muc.de ([193.149.48.1]:25830 helo=mail.muc.de) by eggs.gnu.org with smtp (Exim 4.71) (envelope-from ) id 1gHYSo-0000M9-O0 for emacs-devel@gnu.org; Tue, 30 Oct 2018 14:10:03 -0400 Original-Received: (qmail 28911 invoked by uid 3782); 30 Oct 2018 18:09:37 -0000 Original-Received: from acm.muc.de (p5B1479F4.dip0.t-ipconnect.de [91.20.121.244]) by colin.muc.de (tmda-ofmipd) with ESMTP; Tue, 30 Oct 2018 19:09:36 +0100 Original-Received: (qmail 5789 invoked by uid 1000); 30 Oct 2018 18:09:41 -0000 Content-Disposition: inline In-Reply-To: X-Delivery-Agent: TMDA/1.1.12 (Macallan) X-Primary-Address: acm@muc.de X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 193.149.48.1 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:230840 Archived-At: Hello, Stefan. On Mon, Oct 29, 2018 at 17:08:38 -0400, Stefan Monnier wrote: > >> > Doc strings which specify fully the arguments to these macros, including > >> > their semantics, and say what the macros do. The current doc strings > >> > (at least some of them) for these macros don't do this. > >> I understand this in theory, but I don't know what it means in this > >> concrete case. > > Take a look at, for example, the doc string for pcase-dolist. In its > > entirety, it's this: > Thanks. What do you think of the patch below? I don't think it's enough. > I'd rather keep it defined in terms of its differences w.r.t `dolist`, > but if really needed, we could change the doc so it doesn't rely on > `dolist`s own doc at all. That's a bad idea if it means not saying what the macro does. Not everybody is familiar with dolist by any means. Is dolist's doc string of sufficiently high quality to act as this basis? > We do have to keep the reference to `pcase` because we don't want to > repeat the definition of what a pcase pattern can look like. Yes, I think that's right. Things I believe MUST appear explicitly in the doc string for pcase-dolist: 1. It is a loop over the elements of LIST, which must be a list. 2. It attempts to match the current list element with the supplied PATTERN, which must be a valid pcase style pattern. 3. The BODY forms are evaluated for each element of the list. 4. The purpose of the matching is to create bindings for symbols, and these bindings are in force when the BODY forms are evaluated. 5. When a pattern match fails, ..... (This needs to be stated). > Stefan > diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el > index 57c2d6c3cb..861c900b21 100644 > --- a/lisp/emacs-lisp/pcase.el > +++ b/lisp/emacs-lisp/pcase.el > @@ -281,7 +281,7 @@ pcase-let* > (defmacro pcase-let (bindings &rest body) > "Like `let' but where you can use `pcase' patterns for bindings. > BODY should be a list of expressions, and BINDINGS should be a list of bindings > -of the form (PAT EXP). > +of the form (PATTERN EXP). > The macro is expanded and optimized under the assumption that those > patterns *will* match, so a mismatch may go undetected or may cause > any kind of error." > @@ -302,7 +302,12 @@ pcase-let > ;;;###autoload > (defmacro pcase-dolist (spec &rest body) > - "Like `dolist' but where the binding can be a `pcase' pattern. > + "Superset of `dolist' where the VAR binding can be a `pcase' PATTERN. > +More specifically `dolist's VAR binding is replaced by a PATTERN > +against which each element of the list is matched. > +As in the case of `pcase-let', PATTERN is matched under the assumption > +that it *will* match. > + > \n(fn (PATTERN LIST) BODY...)" > (declare (indent 1) (debug ((pcase-PAT form) body))) > (if (pcase--trivial-upat-p (car spec)) -- Alan Mackenzie (Nuremberg, Germany).