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: emacs-25 1d4887a: Improve documentation of 'pcase' Date: Sat, 23 Jan 2016 12:38:34 +0100 Message-ID: <87vb6kzft1.fsf@web.de> References: <20160123102327.23087.15367@vcs.savannah.gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1453549301 30990 80.91.229.3 (23 Jan 2016 11:41:41 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Jan 2016 11:41:41 +0000 (UTC) Cc: John Wiegley , Emacs Development To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jan 23 12:41:33 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 1aMwZN-0007gy-5B for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 12:41:29 +0100 Original-Received: from localhost ([::1]:56939 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwZM-0000y1-9N for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 06:41:28 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35232) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwWh-00053k-3z for emacs-devel@gnu.org; Sat, 23 Jan 2016 06:38:44 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMwWf-0005FU-RF for emacs-devel@gnu.org; Sat, 23 Jan 2016 06:38:43 -0500 Original-Received: from mout.web.de ([212.227.15.4]:61519) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMwWb-0005DR-R4; Sat, 23 Jan 2016 06:38:38 -0500 Original-Received: from drachen.dragon ([92.77.162.209]) by smtp.web.de (mrweb004) with ESMTPSA (Nemesis) id 0MdpWf-1alv7e1pEr-00PcPE; Sat, 23 Jan 2016 12:38:35 +0100 In-Reply-To: (Eli Zaretskii's message of "Sat, 23 Jan 2016 10:23:28 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-Provags-ID: V03:K0:su722/JMfRFoFP7vFAFH7U3EWk+UiSxJkYwue1mwBXVv1JZDXeE aWuVbvKPHw9Rs8M23imMFAqUt0wjMY/a1U7NQjU6cmTEuY8SXSIL8ltPBw6ZGF9xDc65ICq 68L+k/U/GFm8qfJedv8owdCRSEuZh4/SYfGC+vl5PmyiMDOiOItsi5lkUYwpODnZiz34JYm JFQEmWWpBfNwbRvrVCCrg== X-UI-Out-Filterresults: notjunk:1;V01:K0:geQ9IWnfX0o=:WLqbJtEDHU4Mp8POrHQEQf tyW2E1YhBSW7myT5wMpI7M7PhEU/lAJ1dtmuruAgbDghvZsxQ2HNdyM7VFFh5eQ1rl283JX7k ItfEX6ca3xeSwTU/peGb5H2FUU00bAFNuWk1Snh8KxuhQRFK96iIBDCbSgaoK4+7EdzNajY6S 0NBD0wOaV4KzB0z+VrIAHAxYl36PY5EocwxRYjx2/EKPSD5w8vDx9mLhNyZxWa9tg3UN2eyii fI1f5cRRZg9ladP8SYKE15fKihMXr1acJMyxT0QRZMqlV1VZz4zuoubouBZQ6c/MtGwX1N7Tv WIyoJgc1XH9nzd1fuF4OId7NCbfbTjzoHDxjL6uYxlJWZPDyh3TW6x2J3phZv+vxWc+5ctHst 3MOgSSjbuLTfPlA1qnmV8nOY+gFaG+vDKhNhpxFWSPlxsEpn7bTNltWWqyAxdrXQLb596TFr7 DB+r+DPi3ZlGMoNhw6axrNG8/90Y9DXuYIcX3EYOHa6g3EsOp1AtuI/cb3ccBwLoPM+f1rXY5 vSauOjMeDBkBscr0fng/w0K3I7Qn40+/xq9jzr1olfnUv9nhK5AB5zLQIXdLKEiUHSwTk0Icf 0WZB4Vr/FBubqDB3gVVe6Yiqn4UnYUWPBOKlk7izwEvX4r3ItKH/qlkqjZSbJj0E+MJhkAoSU PtQp+xwsHOGn7RtEVtG5g90DMK6w81A6/XUNZSbv9tKh0W8FLPb+EOTaLkC5MUaJMZlDWwdVM UYWaOZ6XYfQ5ej/oXiiyjqI3/SErby3ZPq3UM019V7CCuMmSaljP4b+MkKFmsieycUCp4Zuz X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.15.4 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:198629 Archived-At: Hi Eli, thanks for finalizing this stuff. Some comments: > -To compare a particular value against various possible cases, the macro > -@code{pcase} can come handy. It takes the following form: > +The @code{cond} form lets you choose between alternatives using > +predicate conditions that compare values of expressions against > +specific values known and written in advance. However, sometimes it > +is useful to select alternatives based on more general conditions that > +distinguish between broad classes of values. The @code{pcase} macro > +allows to choose between alternatives based on matching the value of > +an expression against a series of patterns. A pattern can be a > +literal value (comparison to literal values is what @code{cond} > does), That does sound more as a description of `cl-case' -- typo? > +@defmac pcase expression &rest clauses > +Evaluate @var{expression} and choose among an arbitrary number of > +alternatives based on the value of @var{expression}. The possible > +alternatives are specified by @var{clauses}, each of which must be a > +list of the form @code{(@var{pattern} @var{body-forms})}. I think we should write @code{(@var{pattern} . @var{body-forms})} ^ if we mean that BODY-FORMS is a list, or use an ellipsis: "...", as you do later. > +The @var{pattern} part of a clause can be of one of two types: > +@dfn{QPattern}, a pattern quoted with a backquote; or a > +@dfn{UPattern}, which is not quoted. UPatterns are simpler, so we > +describe them first. I had hoped we can get rid of the QPattern/Upattern distinction. Is it too late to change that? In particular, we wanted to speak of just patterns instead of Upatterns. > +@item '@var{val} > +Matches if the value being matched is @code{equal} to @var{val}. > +@item @var{atom} > +Matches any @var{atom}, which can be a keyword, a number, or a string. > +(These are self-quoting, so this kind of UPattern is actually a > +shorthand for @code{'@var{atom}}.) Can we say "matches any (equal) atom"? This makes a difference for strings. And actually, this is not true for floats, only for integers (I'm not sure why). > +Matches if @var{boolean-expression} evaluates to non-@code{nil}. This > +allows to include in a UPattern boolean conditions that refer to > +symbols bound to values (including the value being matched) by > +previous UPatterns. Typically used inside an @code{and} UPattern, see > +below. For example, @w{@code{(and x (guard (< x 10)))}} is a pattern > +which matches any number smaller than 10 and let-binds the variable > +@code{x} to that number. Maybe we should use @w{@code{(and x (pred numberp) (guard (< x 10)))}} instead in the example, because without the numberp test, the pattern will raise an error if x is not bound to a number. > +@table @code > +@item `(@var{qpattern1} . @var{qpattern2}) > +Matches if the value being matched is a cons cell whose @code{car} > +matches @var{qpattern1} and whose @code{cdr} matches @var{qpattern2}. > +@item `[@var{qpattern1} @var{qpattern2} @dots{} @var{qpatternm}] > +Matches if the value being matched is a vector of length @var{m} whose > +@code{0}..@code{(@var{m}-1)}th elements match @var{qpattern1}, > +@var{qpattern2} @dots{} @var{qpatternm}, respectively. > +@item `(,@var{upattern1} ,@var{upattern2} @dots{}) > +Matches if the value being matched is a list whose elements match the > +corresponding @var{upattern1}, @var{upattern2}, etc. > +@item @var{atom} > +Matches if corresponding element of the value being matched is > +@code{equal} to the specified @var{atom}. > +@item ,@var{upattern} > +Matches if the corresponding element of the value being matched > +matches the specified @var{upattern}. Please decide if you include the backquote in all examples, or in none. The thing we name "qpattern" is without backquote, so with the current wording, I would leave the backquote out. And these templates are not covering everything possible, e.g. you can also have `(,up1 . ,up2) or `(,up qp1) I think I would reorganize that paragraph. Many, many thanks so far. Regards, Michael.