From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: emacs-25 1d4887a: Improve documentation of 'pcase' Date: Sat, 23 Jan 2016 15:27:13 +0200 Message-ID: <837fj05sum.fsf@gnu.org> References: <20160123102327.23087.15367@vcs.savannah.gnu.org> <87vb6kzft1.fsf@web.de> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453555641 8303 80.91.229.3 (23 Jan 2016 13:27:21 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 23 Jan 2016 13:27:21 +0000 (UTC) Cc: jwiegley@gmail.com, emacs-devel@gnu.org To: Michael Heerdegen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jan 23 14:27:21 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 1aMyDn-0004nY-7G for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 14:27:19 +0100 Original-Received: from localhost ([::1]:57352 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMyDm-0006Nm-Cg for ged-emacs-devel@m.gmane.org; Sat, 23 Jan 2016 08:27:18 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:60675) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMyDW-0006NU-HW for emacs-devel@gnu.org; Sat, 23 Jan 2016 08:27:03 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aMyDR-0007GW-HG for emacs-devel@gnu.org; Sat, 23 Jan 2016 08:27:02 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:48521) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aMyDR-0007GH-Dk; Sat, 23 Jan 2016 08:26:57 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:2208 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aMyDO-0003B2-P2; Sat, 23 Jan 2016 08:26:55 -0500 In-reply-to: <87vb6kzft1.fsf@web.de> (message from Michael Heerdegen on Sat, 23 Jan 2016 12:38:34 +0100) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2001:4830:134:3::e 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:198639 Archived-At: > From: Michael Heerdegen > Cc: John Wiegley , > Emacs Development > Date: Sat, 23 Jan 2016 12:38:34 +0100 > > Hi Eli, > > thanks for finalizing this stuff. You are welcome. > > -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'? > > +@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. > > +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. > > +@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? > > +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. > > > +@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. > 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. > 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. Thanks for reviewing it.