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: Mon, 25 Jan 2016 14:49:20 +0100 Message-ID: <87h9i1rcpr.fsf@web.de> References: <20160123102327.23087.15367@vcs.savannah.gnu.org> <87vb6kzft1.fsf@web.de> <837fj05sum.fsf@gnu.org> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1453729802 13538 80.91.229.3 (25 Jan 2016 13:50:02 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 25 Jan 2016 13:50:02 +0000 (UTC) Cc: jwiegley@gmail.com, emacs-devel@gnu.org To: Eli Zaretskii Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Jan 25 14:49:54 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 1aNhWj-0008WS-C6 for ged-emacs-devel@m.gmane.org; Mon, 25 Jan 2016 14:49:53 +0100 Original-Received: from localhost ([::1]:38686 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNhWi-0001ox-Fc for ged-emacs-devel@m.gmane.org; Mon, 25 Jan 2016 08:49:52 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60272) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNhWR-0001iF-8J for emacs-devel@gnu.org; Mon, 25 Jan 2016 08:49:39 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNhWL-0002zB-0y for emacs-devel@gnu.org; Mon, 25 Jan 2016 08:49:35 -0500 Original-Received: from mout.web.de ([212.227.15.4]:57294) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNhWG-0002yA-7G; Mon, 25 Jan 2016 08:49:24 -0500 Original-Received: from drachen.dragon ([92.77.162.209]) by smtp.web.de (mrweb003) with ESMTPSA (Nemesis) id 0Lfipe-1Zlsap2jCk-00pPPu; Mon, 25 Jan 2016 14:49:21 +0100 In-Reply-To: <837fj05sum.fsf@gnu.org> (Eli Zaretskii's message of "Sat, 23 Jan 2016 15:27:13 +0200") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-Provags-ID: V03:K0:8MNsYDQD3Ux7+zrPM9iprAD8y4DtwKX1D4lgZrd28rxZ3cVt4bC RULMYMVi4D79Pl6z+tMmNIFtb1K3MdPvA1J76fHOqn77PsAyf7nOx9cmhcmZss14v+IKhF+ XmTUfNMye0nLJHzZ2SDAe+/qD4i2jMa9Ysx6ca5SZUiH7deXD+3nKlXGv4mYoFKAKmvHLK7 qlJAuffENVIuK4kFz+uIA== X-UI-Out-Filterresults: notjunk:1;V01:K0:Y6i0Lz5VKmc=:3m65qdLwLBy1azPkjb8pe5 itcRpqVqEAwuMCd0riUsW0wddvpQRuyE9d/u3DScnuEu4XzhQiWolxnVgc1rBFJ3SheTsuYE6 ymwzIh4azSkDbt5a+2oBuwa24hNxzbpfqtjHiJbXMSmyBmJJjzLV3RsZ9kUU4Y5jeSFlE+G3i vL1dfVG8vUd5ZAos1giqbIRllMiZiuk7/avHrOV4tnKY/NmhvbYMa8+GBXQsHkfgChY2yMXnM Qfr6lR+9lkQL7QFpazoUvziUy1ERXdk5QuTidXMNa43yo2xb4V/964QeGnH8jU/+b1xG1pUul w0EDyA1Ro0xFG5gomlnm7U0ecgCo0leNzE3ZKgsZPnlsUNBZnGyTDJy17ic3wBAzlATKYWsQL tOowIe4Ml93H8vRwCm/oMlm2QVKxJQaUTu+OzQd7atk7st3OfyyF8JW0xG21KAG8ppZLFfO8D 1MAAcer/TbQE7yq1GkSDqSvoFKxJ7o7z9PvlBHq7XwJuS8WVEuiLsIy1mM6zSkqZfSnU31ao1 KRN8awNyOanT4XJar6TNIeF2b/ZLhElvdBhIOrbd1cOvleiTERN47FrUZe4zU4VhhO8IHS6h9 SxYro/MolhsjfVpvSwCNWQFVY24y9BD39RmEz7uOBThR84vEWI1ep0H0djH2qPZxn2yE6fBaE h6u9dsAwRbOLACnFB53KLZLQs37HcPBzYBTRWnuTQfj1wUVB0my548n+SY1tvCYbbqVz05Uwo tBjrO/sofajJsWXeZ34KRLIyrRJqthKFqm2xKNhoqcED4tW8DrmnbRRf4+3YJT+WdQT7X/Y4 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:198761 Archived-At: Eli Zaretskii writes: > > > -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? > > No, of course not. What's incorrect about that text regarding > 'pcase'? "A pattern can be a literal value (comparison to literal values is what @code{cond} does)". Comparison to literal values is what case does. cond evaluates expressions and looks whether the value is non-nil. > > > +@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. > > Sorry, I don't understand why. "Forms", in plural, means there are > more than one of them. I'm okay with adding @dots{}, if you somehow > think it's required. But using a cons cell would be too confusing, as > none of the examples uses that form. But if body-forms is a list, you would get a template like (pattern (expr1 expr2)) and that's wrong. > > > +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. > > Find a better name for them, and we can switch. Using "pattern" for > UPattern is not a good idea, IMO, as that word is too generic, and we > are describing a feature where we must use that word all the time. I just call them pcase patterns. > > > +@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. > > Why does it make a difference? Strings and floats don't only match themselves, but also any equal string/float. That's important, since not everything is always tested with `euqal' - multiple occurrences of a symbol are turned into `eq' tests, for example. > > > +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. > > I don't think we need to be so pedantic in "for example" fragments, > they are just there to illustrate a point. But the reader may get the impression that such things are tested implicitly, or the error is silenced and the pattern just doesn't match. That's why I think it's a bad example without the additional test. > > > +@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. > > I did. The two last ones belong to the "issues" I raise in a separate > mail: I Think they don't have a place in this list, at least not in > that syntax. When that discussion ends to my satisfaction, I will fix > whatever needs to be fixed. Ok, I hope I don't miss it. > > The thing we name "qpattern" is without backquote, so with the current > > wording, I would leave the backquote out. > > There's no backquote in the QPatterns in the text I wrote, see above. > the backquote is explicitly prepended. So I'm not sure how to > understand this comment. I think Stefan has answered this question in a different post. Sorry if he answered other things already that I tell here. > > 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. > > When the fog and the dust settle down, perhaps I will. For now, this > is the best I could come up with, and it closely follows what you > wrote in your guide, btw. Ok. Thanks, Michael.