From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#31311: 27.0; doc of `pcase' Date: Sun, 29 Apr 2018 09:03:32 -0700 (PDT) Message-ID: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: blaine.gmane.org 1525017734 17705 195.159.176.226 (29 Apr 2018 16:02:14 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 29 Apr 2018 16:02:14 +0000 (UTC) To: 31311@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sun Apr 29 18:02:10 2018 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1fCom7-0004Si-W3 for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 18:02:08 +0200 Original-Received: from localhost ([::1]:56054 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCooE-0004CU-Ew for geb-bug-gnu-emacs@m.gmane.org; Sun, 29 Apr 2018 12:04:18 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56402) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCoo2-0004Ac-5V for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:04:07 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fConz-0003nF-0v for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:04:06 -0400 Original-Received: from debbugs.gnu.org ([208.118.235.43]:35137) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fCony-0003nB-S7 for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fCony-0002K2-Ge for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sun, 29 Apr 2018 16:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: report 31311 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: X-Debbugs-Original-To: bug-gnu-emacs@gnu.org Original-Received: via spool by submit@debbugs.gnu.org id=B.15250178328906 (code B ref -1); Sun, 29 Apr 2018 16:04:02 +0000 Original-Received: (at submit) by debbugs.gnu.org; 29 Apr 2018 16:03:52 +0000 Original-Received: from localhost ([127.0.0.1]:43034 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fConn-0002Ja-LM for submit@debbugs.gnu.org; Sun, 29 Apr 2018 12:03:52 -0400 Original-Received: from eggs.gnu.org ([208.118.235.92]:37176) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1fConl-0002JM-I6 for submit@debbugs.gnu.org; Sun, 29 Apr 2018 12:03:50 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fCone-0003ki-T1 for submit@debbugs.gnu.org; Sun, 29 Apr 2018 12:03:44 -0400 Original-Received: from lists.gnu.org ([2001:4830:134:3::11]:48980) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fCone-0003kd-Px for submit@debbugs.gnu.org; Sun, 29 Apr 2018 12:03:42 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:56379) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fCond-000480-1b for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:03:42 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fConZ-0003jr-Th for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:03:41 -0400 Original-Received: from aserp2120.oracle.com ([141.146.126.78]:56964) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1fConZ-0003jb-Kt for bug-gnu-emacs@gnu.org; Sun, 29 Apr 2018 12:03:37 -0400 Original-Received: from pps.filterd (aserp2120.oracle.com [127.0.0.1]) by aserp2120.oracle.com (8.16.0.22/8.16.0.22) with SMTP id w3TG3Zt1123026 for ; Sun, 29 Apr 2018 16:03:35 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=oracle.com; h=mime-version : message-id : date : from : sender : to : subject : content-type : content-transfer-encoding; s=corp-2017-10-26; bh=9Ueet0ctWo+4MmwK2yzc/3SbyepRQs6MRJvf14ctINA=; b=nfQ+lcNkOUtus8aw+60yv/W8glJFJjdzRV8TZD+6nDpFYstyVmKnDhZBuw8yBfbxZubd 5xjjdMBX1Z1wOM4+tUiLe7zPFZO/lnNbgUmjnczybiA4f7ZtiwchfDjHQuUctSdghbpO XkpLMtz4LyNVhi6VqSQx81pyzSGk8/W2iKTiupCG0uK+4w4Bc1mNQEMoDxglFIy8XE4j YBqFSSds9/MHoMcuyKPRy6zhX5MpqJJmZ/+qcvfn0UHUArzxqMyeWd/5ro2MAOL9Oaa6 9R26xfxmngkfz2IK4alfvY48WJkvKINz0StI5d0OT3M15KyQgChOD512UuFypuuULOwV CA== Original-Received: from aserv0022.oracle.com (aserv0022.oracle.com [141.146.126.234]) by aserp2120.oracle.com with ESMTP id 2hmgxfhxm3-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 29 Apr 2018 16:03:35 +0000 Original-Received: from userv0121.oracle.com (userv0121.oracle.com [156.151.31.72]) by aserv0022.oracle.com (8.14.4/8.14.4) with ESMTP id w3TG3YHM012350 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Sun, 29 Apr 2018 16:03:34 GMT Original-Received: from abhmp0008.oracle.com (abhmp0008.oracle.com [141.146.116.14]) by userv0121.oracle.com (8.14.4/8.13.8) with ESMTP id w3TG3XEC030876 for ; Sun, 29 Apr 2018 16:03:34 GMT X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.9.1 (1003210) [OL 16.0.4678.0 (x86)] X-Proofpoint-Virus-Version: vendor=nai engine=5900 definitions=8878 signatures=668698 X-Proofpoint-Spam-Details: rule=notspam policy=default score=0 suspectscore=1 malwarescore=0 phishscore=0 bulkscore=0 spamscore=0 mlxscore=0 mlxlogscore=999 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1711220000 definitions=main-1804290160 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x [generic] [fuzzy] X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6.x X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:145822 Archived-At: 1. Please rename Elisp manual node `Pattern matching case statement'. It should use Title Case (not Sentence case), like the other nodes. And do not refer to "case", as the other index entries that match `case' have nothing to do with conditionals. And the node name can be shorter, e.g., `Pattern-Matching Conditional'. 2. Don't use ATOM unless you mean any atom, even if you explain subsequently that you really mean a self-evaluating atom. In particular, an arbitrary symbol is an atom, and (especially if ATOM is described before SYMBOL) ATOM would seem to cover the SYMBOL case, which it does not. Just use "CONSTANT" instead of "ATOM". AFAIK, every self-evaluating sexp in Emacs Lisp satisfies `atomp' (but not everything that satisfies `atomp' is a self-evaluating sexp). The doc should also make clear whether the ATOM clause covers a symbol defined using `defconst'. The answer seems to be no; it seems to be covered instead by the SYMBOL clause. 3. The doc string (but not the Elisp manual, node `Pattern matching case statement') refers to "the object" without ever specifying what it is. This makes all of the specifications that use "the object" meaningless: 'VAL, (pred FUN), and (app FUN PAT). The manual uses "the value being matched" instead, which is OK (understandable). Still, it would be clearer to give a name to "the value being matched" at the beginning: EXPVAL, for example, at the place where you say, "based on the value of EXPRESSION". Similarly, replace "value of the EXPRESSION that is the first argument of 'pcase'" by the name you give that (e.g. EXPVAL). 4. The doc string seems to be describing a different animal from the manual. Try to harmonize the two descriptions, including wrt the order of pattern presentation. 5. Don't use "QPattern" and "UPattern". Use "Q pattern" and "U pattern", or (probably better) "Q-pattern" and "U-pattern". 6. This part of the description of `guard' is unclear, to me: For example ... and let-binds the variable 'x' to that number. I see nothing in the descriptions of `guard' and `and' that indicates why `x' would be let-bound in this example. 7. The doc-string descriptions do not correspond to those in the manual, in several cases. E.g. (app FUN PAT) is different from (app FUNCTION UPATTERN). Is the pattern necessarily a U-pattern? Similary for `or' etc. 8. Please check for typos. E.g., "Matches if one the argument UPatterns matches." 9. This is not clear to m: "For this reason, if any of the UPatterns let-bind symbols to the matched value, they should all bind the same symbols." Should it instead say that they should all bind the same symbols to the matched value"? Also, does a similar thing need to be said for `and'? 10. This text: "The function calls used in the 'pred' and 'app' UPatterns can have one of the following forms" seems wrong. Presumably what it is trying to say is that PREDFUN and FUNCTION "can have one of the following forms". Those forms are not necessarily function calls. Similarly, for the text "The FUNCTION call can use one of the forms described below" - just say "FUNCTION can use...", not "The FUNCTION call can use...". 11. Do not say "lambda-function". Say either "lambda expression" or "anonymous function". There is no such thing as a lambda function. You might also want to xref node `Lambda Expressions'. 12. "Here is an illustrative example" -> "Here is an example". 13. "you can use backquoted patterns that are more powerful" -> "you can use backquoted patterns, which that are more powerful". The comma is important. This part of the node is not "in addition" to some previous description of backquoted patterns; this _is_ the description of backquoted patterns, i.e., Q-patterns. What came before was the description of unquoted patterns, i.e., U-patterns. 14. "(note that this example requires lexical binding, *note Lexical Binding::)". Say _why_ this is the case, not just that it is true. Why does it require lexical binding? Also, the code needs wrapping; two of the lines are too long: (funcall (evaluate fun env) (evaluate arg env)) -> (funcall (evaluate fun env) (evaluate arg env)) (lambda (val) (evaluate body (cons (cons arg val) env))) -> (lambda (val) (evaluate body (cons (cons arg val) env))) 15. Break up the paragraph that begins "Here '`(add ,x ,y)' is a..." 16. All of the following text in the _doc string_ is pretty much incomprehensible, to me. It's not clear what it's trying to say or even, in some cases, how it relates to `pcase' at all. And most of it seems to have no correspondence in the manual. -- (radix-tree-leaf VPAT) Not documented. -- (cl-struct TYPE &rest FIELDS) Pcase patterns to match cl-structs. Elements of FIELDS can be of the form (NAME PAT) in which case the contents of field NAME is matched against PAT, or they can be of the form NAME which is a shorthand for (NAME NAME). -- (seq &rest PATTERNS) Build a 'pcase' pattern that matches elements of SEQUENCE. The 'pcase' pattern will match each element of PATTERNS against the corresponding element of SEQUENCE. Extra elements of the sequence are ignored if fewer PATTERNS are given, and the match does not fail. -- (eieio &rest FIELDS) Pcase patterns to match EIEIO objects. Elements of FIELDS can be of the form (NAME PAT) in which case the contents of field NAME is matched against PAT, or they can be of the form NAME which is a shorthand for (NAME NAME). -- `QPAT Backquote-style pcase patterns. QPAT can take the following forms: (QPAT1 . QPAT2) matches if QPAT1 matches the car and QPAT2 the c= dr. [QPAT1 QPAT2..QPATn] matches a vector of length n and QPAT1..QPATn ma= tch its 0..(n-1)th elements, respectively. ,PAT matches if the pcase pattern PAT matches. ATOM matches if the object is 'equal' to ATOM. ATOM can be a symbol, an integer, or a string= . In GNU Emacs 27.0.50 (build 3, x86_64-w64-mingw32) of 2018-03-21 Repository revision: e70d0c9e66d7a8609450b2889869d16aeb0363b5 Windowing system distributor `Microsoft Corp.', version 6.1.7601 Configured using: `configure --without-dbus --host=3Dx86_64-w64-mingw32 --without-compress-install -C 'CFLAGS=3D-O2 -static -g3''