From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Andy Moreton Newsgroups: gmane.emacs.devel Subject: Re: Replace trivial pcase occurrences in the Emacs sources Date: Mon, 29 Oct 2018 14:47:02 +0000 Message-ID: References: <20151216202605.GA3752@acm.fritz.box> <56892BDA.6060103@dancol.org> <871t9yk98g.fsf@fencepost.gnu.org> <568936F0.3060505@yandex.ru> <87wprqitj5.fsf@fencepost.gnu.org> <56893C8C.3060200@yandex.ru> <87oad2irtd.fsf@fencepost.gnu.org> <5689456A.1010601@yandex.ru> <87egdy8tyz.fsf@fencepost.gnu.org> <56895FDE.4060406@yandex.ru> <8760za8r4a.fsf@fencepost.gnu.org> <87h9iunkcg.fsf@web.de> <87h8hc4xw2.fsf_-_@web.de> <83tvlcsnee.fsf@gnu.org> <86mur137n8.fsf@gmail.com> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Trace: blaine.gmane.org 1540824367 20357 195.159.176.226 (29 Oct 2018 14:46:07 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Mon, 29 Oct 2018 14:46:07 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (windows-nt) To: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Mon Oct 29 15:46:03 2018 Return-path: Envelope-to: ged-emacs-devel@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gH8nq-0005Bh-S2 for ged-emacs-devel@m.gmane.org; Mon, 29 Oct 2018 15:46:02 +0100 Original-Received: from localhost ([::1]:46072 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gH8px-0004dL-BI for ged-emacs-devel@m.gmane.org; Mon, 29 Oct 2018 10:48:13 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:52159) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gH8pF-0004d5-Np for emacs-devel@gnu.org; Mon, 29 Oct 2018 10:47:30 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gH8pB-0007Fd-4a for emacs-devel@gnu.org; Mon, 29 Oct 2018 10:47:29 -0400 Original-Received: from [195.159.176.226] (port=35705 helo=blaine.gmane.org) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gH8p5-00075q-Oh for emacs-devel@gnu.org; Mon, 29 Oct 2018 10:47:21 -0400 Original-Received: from list by blaine.gmane.org with local (Exim 4.84_2) (envelope-from ) id 1gH8mp-0003z4-Th for emacs-devel@gnu.org; Mon, 29 Oct 2018 15:44:59 +0100 X-Injected-Via-Gmane: http://gmane.org/ Original-Lines: 77 Original-X-Complaints-To: usenet@blaine.gmane.org Cancel-Lock: sha1:jTZjxpez+CZV88lU0T5P7hDRvk8= X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 195.159.176.226 X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.21 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" Xref: news.gmane.org gmane.emacs.devel:230767 Archived-At: On Sun 28 Oct 2018, Stefan Monnier wrote: >> pcase-lambda, pcase-let, pcase-let*, and pcase-dolist still have no >> meaningful documentation, > > Not sure what kind of documentation would be more meaningful, sorry. > Do you happen to have concrete questions about them which aren't answered > by their docstrings? Here is the documentation for lambda - reasonably complete and descriptive, and with links to other referenced symbols: (lambda ARGS [DOCSTRING] [INTERACTIVE] BODY) Return a lambda expression. A call of the form (lambda ARGS DOCSTRING INTERACTIVE BODY) is self-quoting; the result of evaluating the lambda expression is the expression itself. The lambda expression may then be treated as a function, i.e., stored as the function value of a symbol, passed to ‘funcall’ or ‘mapcar’, etc. ARGS should take the same form as an argument list for a ‘defun’. DOCSTRING is an optional documentation string. If present, it should describe how to call the function. But documentation strings are usually not useful in nameless functions. INTERACTIVE should be a call to the function ‘interactive’, which see. It may also be omitted. BODY should be a list of Lisp expressions. Contrast this with the `pcase-lambda' docstring: (pcase-lambda LAMBDA-LIST &rest BODY) Like ‘lambda’ but allow each argument to be a pattern. I.e. accepts the usual &optional and &rest keywords, but every formal argument can be any pattern accepted by ‘pcase’ (a mere variable name being but a special case of it). This mentions "each argument", but the arguments shown have `LAMBDA-LIST' (which is not described) and BODY - is this an argument that can be pattern ? There is no discussion of how pattern match failure is treated - what happens ? Please note that users can only read what is in the docstring, not the unwritten intentions of the docstring author. The `pcase-let' docstring warns that it assumes patterns will match and fails arbitrarily if that is not the case. This seems a strng indicator that this macro is unsafe for use in any user code. The `pcase-let*' docstring does not mention a similar pattern matching assumption, so does it also behave randomly on pattern match failure ? The `pcase-dolist' docstring is entirely uninformative. None of the arguments are described, nor are the semantics of the macro. The docstring needs complete replacement. The pcase-exhaustive docstring mentions that an error is signalled if pattern matching fails, but which error ? How are users supposed to write code that determines that a pattern match failure has occurred rather than any other error ? Which error is signalled should be part of the interface contract here, and should be documented. There are no entry in the manual for the pcase macros, and there are no meaningful examples to show proper usage of each of the pcase match pattern types. > Could you clarify what you find problematic in those uses? Given that the documentation is insufficient to describe the syntax and semantics of these macros, how can ordinary users discern the meaning of a pcase construct that they read in code ? How can they learn to write code containing pcase macros which has the user's desired semantics ? How can users learn when these constructs may be beneficial and when they should be avoided ? AndyM