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: Mon, 25 Jan 2016 18:23:07 +0200 Message-ID: <83d1sp39xw.fsf@gnu.org> References: <20160123102327.23087.15367@vcs.savannah.gnu.org> <87vb6kzft1.fsf@web.de> <837fj05sum.fsf@gnu.org> <87h9i1rcpr.fsf@web.de> Reply-To: Eli Zaretskii NNTP-Posting-Host: plane.gmane.org X-Trace: ger.gmane.org 1453738978 10935 80.91.229.3 (25 Jan 2016 16:22:58 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Mon, 25 Jan 2016 16:22:58 +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 Mon Jan 25 17:22: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 1aNjum-0004yH-9y for ged-emacs-devel@m.gmane.org; Mon, 25 Jan 2016 17:22:52 +0100 Original-Received: from localhost ([::1]:39523 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNjul-00075s-QK for ged-emacs-devel@m.gmane.org; Mon, 25 Jan 2016 11:22:51 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:53995) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNjui-00075l-Dj for emacs-devel@gnu.org; Mon, 25 Jan 2016 11:22:49 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aNjud-0007pS-8g for emacs-devel@gnu.org; Mon, 25 Jan 2016 11:22:48 -0500 Original-Received: from fencepost.gnu.org ([2001:4830:134:3::e]:40306) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aNjud-0007pO-6Q; Mon, 25 Jan 2016 11:22:43 -0500 Original-Received: from 84.94.185.246.cable.012.net.il ([84.94.185.246]:4749 helo=HOME-C4E4A596F7) by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_128_CBC_SHA1:128) (Exim 4.82) (envelope-from ) id 1aNjub-0003HP-Uc; Mon, 25 Jan 2016 11:22:42 -0500 In-reply-to: <87h9i1rcpr.fsf@web.de> (message from Michael Heerdegen on Mon, 25 Jan 2016 14:49:20 +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:198790 Archived-At: > From: Michael Heerdegen > Cc: jwiegley@gmail.com, emacs-devel@gnu.org > Date: Mon, 25 Jan 2016 14:49:20 +0100 > > "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. What I meant was that 'cond' can be used to compare against literal values. I will tweak the wording to make that more clear, thanks. > > > > +@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. I didn't say body-forms is a list. I just said that there can be more than one form there. > > > > +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. Too wordy, IMO. Try using that in the descriptions of each pattern, and you quickly get a mouthful. > > > > +@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. But there's no reference to 'eq' or 'equal' in that text. It just says "matches". > > > > +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. There's no reason to believe readers will get such an expression from something that is clearly an incomplete fragment. > > > 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. He just said that he (and evidently you as well) use a different "language" when you talk about QPatterns. I think my "language" is more easily understood and matches the actual usage better, even if it's pedantically less rigorous. Thanks.