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: The poor state of documentation of pcase like things. Date: Sat, 19 Dec 2015 21:42:01 +0100 Message-ID: <871taimaqu.fsf@web.de> References: <20151216202605.GA3752@acm.fritz.box> <87fuyytq6b.fsf@web.de> <20151219183057.GA2238@acm.fritz.box> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: ger.gmane.org 1450557745 19720 80.91.229.3 (19 Dec 2015 20:42:25 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 19 Dec 2015 20:42:25 +0000 (UTC) Cc: emacs-devel@gnu.org To: Alan Mackenzie Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Dec 19 21:42:16 2015 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 1aAOKU-0007m6-RI for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 21:42:15 +0100 Original-Received: from localhost ([::1]:38580 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAOKU-0004Pi-4I for ged-emacs-devel@m.gmane.org; Sat, 19 Dec 2015 15:42:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39056) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAOKQ-0004PJ-84 for emacs-devel@gnu.org; Sat, 19 Dec 2015 15:42:11 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1aAOKN-0004Ss-12 for emacs-devel@gnu.org; Sat, 19 Dec 2015 15:42:10 -0500 Original-Received: from mout.web.de ([212.227.17.12]:59328) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1aAOKM-0004Sg-Nm for emacs-devel@gnu.org; Sat, 19 Dec 2015 15:42:06 -0500 Original-Received: from drachen.dragon ([90.186.0.6]) by smtp.web.de (mrweb103) with ESMTPSA (Nemesis) id 0Maaur-1Zuel02cRt-00KB7Z; Sat, 19 Dec 2015 21:42:04 +0100 In-Reply-To: <20151219183057.GA2238@acm.fritz.box> (Alan Mackenzie's message of "Sat, 19 Dec 2015 18:30:57 +0000") User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.0.50 (gnu/linux) X-Provags-ID: V03:K0:25ZTz6XBSQsKKe5GzkI6wck36tg1dfsoaxLc+awwFPUul9+bSAZ ToTuSqddZSuUp8lSYb8+YZ7kiLbdb8DVHGZ4Y4MFV8U65DlpzxgVBgQMO98jorJa6ct+LUQ /sU0wRmEamOQR8snldncx96MPvYAR9s07yK5HN/49BiR9UsXVVjq+gSHEfA78GoLkK1FSsW WauBYGBYYjwquRf/GFqPw== X-UI-Out-Filterresults: notjunk:1;V01:K0:EmSEaYaYlBA=:0TpqlBViqHnXANZRpQBccl 8Xo3JJvFckZWC7N/CP7WoeyHlJxHIM0fv4dZWkSCetRd5A/XFgN/M+naoCQZKYQJjcwfsVN1z mtn7IpD0KovZpr3TLC6Ltgu08jDELaS+Fk/4AI7Pi0Zv355BW7T2l7o7lTzZGx6+IvRA9EiDt us1Oeahht4HFTQUyx3EN6pZZz9F89505M2jAf0eVtikqoFWolBdO+uNF0Vv5bvabqe6cn2MK/ iSfnbsnySY6jDCY4Rf06CpMKaPhET0Fz2Fpvx6dzaXcTDDyU6tkeGocCWOGmqSIv2FhXbOlvR 5/qS8lcWAb0ewS/9Jb6WxUkBMYhCUDLIASZ00CZz5wMvci34mRI5pVPL1dPR6CSjv+d1lnxGC T85uzG/YScKSqpExHyUTiI4u9bn0711R2rfUxsz2fvIxeHZvOn7BrXVmZtsE5KcqPbAnAy54y bl3vTeLqCWn8604p3FIMqt7hSG9lxsFDd5mViP0eUEBysnLCMvo/IyhJKEOQDIdNaLJpCXOsl I5GZY5IsA6GOWP9MVYQMWxuanqlGGflEdU+Rvqv1ao7j13QgrqfDDXgCGioBXEDx24xAALf7G kUlmYCk8ShB4Ozm2kyQH4Mk54xIOfRygReJ9maQnrjDBPa22Wooly59hBvgVIazCT43htooTp DnSsNlmZ+TCB9IpQUcrX6yM28hXumagV1/ydSu5peWmH34L8cdpqA0/BiU5NB3xbUyB14CQaU C2+KU2iVF/7aPeY4bMhYcfCThM/vDmolCZKtRh68GXADKFIdcVqVQQbjjaSQqwAVq5Ks1Tb5 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 212.227.17.12 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:196524 Archived-At: Alan Mackenzie writes: > I wish you a happy one, though. You too! > > As far as I understand how Stefan used to work, most of the semantics of > > most of the pcase derivatives, like `pcase-let', are not yet 100% fixed, > > we are not yet sure how useful we are, or if they may later be better be > > replaced by other forms that are more general, etc. > > Yet the said functions have been committed on the release branch I think Stefan used the term "don't advertise them yet too much" for such things. > and are already in widespread use throughout the Emacs sources. As > Eli notes, there're around 90 uses of pcase-let and pcase-let*. Could be they have nearly all been placed there by Stefan ;-) > They're essentially undocumented. That makes the code that uses them > essentially unmaintainable, except by those who know, or are prepared to > guess, what these functions do. I can't agree with you that this is > good. This can't be the final state, no doubt. It must be fixed. But we have to do it very carefully, and maybe not completely now: if even Stefan was not sure everywhere what could be written in the documentation and if the code makes much sense, let's not engrave in stone details we are not sure about whether they are true or intended or useful. This does not so much apply to `pcase-let' - I think it's quite clear what it does, though I didn't use it often myself. OTOH, I'm not so sure about `pcase-lambda' for example. How does/should a `pcase-lambda' behave when applied to something that it's "signature" doesn't match? Is it maybe cleaner to move a pcase call just inside the `lambda'? Is the semantics of pcase really the best thing one can use to hook pattern matching into a function, or is there a better one? In practice, only a subset of pcase semantics makes sense for `pcase-lambda' most of the time (mostly, destructuring), you can have "only one clause" contrary to `pcase' - is the resulting code readable?; is `pcase-lambda' a good abstraction/idea? If later we find it's a bad idea, it's not good if we advertise it too much in the manual, because we can't remove it so easily then. > The pcase docstring is getting better, yes. It stil doesn't document > explicitly that the normal meanings of ` and , are suspended. Mmh, but it also doesn't say that the normal meanings of and, or, ' and let are suspended. I think it doesn't have to, because a pcase pattern is not an expression that is evaluated, so symbols with known names can't have the same semantics as a pattern than as a defined function. > There is still no explicit statement of what pcase's ` and , mean. But do we agree that the current docstring completely explains the semantics, even if the definition is recursive? > Maybe I'm expecting too much, and ` and , have no intrinsic meanings in > pcase. But I don't believe that is the case. ``' is a pcase macro (at least now). pcase macros are like Lisp macros, but while Lisp macros expand to Lisp code, pcase macros expand to pcase patterns. The backquote macro ``' in Lisp is a utility that is used to build lists. pcase's ``' is used to build patterns that match lists. The only difference for unquoting (`,'), so to say, is that in the first case it "inserts" an arbitrary "value" at that position, and in the second case, "inserts" an arbitrary pcase pattern (that is responsible to match the element at that place, instead of being a specified constant that matches only itself via `equal'.) If you only unquote symbols, like in `(1 2 ,x) you can imagine that x is already bound to the "right" value, then the thing works much like the standard backquote. That analogy is not so useful for things like `(1 2 ,(pred stringp)) I guess, though you still can imagine that the pattern matches any three-element list whose first two elements are 1, 2, and as third element, anything that fulfills the predicate "stringp" can be "inserted". You can verify by yourself that elements in a backquoted list in pcase "behave" as if they were quoted with a quote (see the 'VAL form) - thus the name "QPattern" - and that the rules for quoted atoms apply as expected, and such things. [ While writing this, I see now that the doc of ``' in the pcase doc is a typical mathematical definition: it is absolutely correct, but doesn't say "what it's good for" and "how to use it". To be honest I also had much trouble to understand it when I learned `pcase'. ] BTW, there is no `,@' unquote splicing in pcase's backquote because it can lead to ambiguity when matching (and would be slow). Regards, Michael.