From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Stefan Monnier Newsgroups: gmane.emacs.devel Subject: EXPVAL in pcase-defmacro docstrings Date: Wed, 30 May 2018 08:28:29 -0400 Message-ID: NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1527683278 21786 195.159.176.226 (30 May 2018 12:27:58 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Wed, 30 May 2018 12:27:58 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) Cc: emacs-devel@gnu.org To: Thien-Thi Nguyen Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Wed May 30 14:27:54 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 1fO0Cn-0005aA-Nw for ged-emacs-devel@m.gmane.org; Wed, 30 May 2018 14:27:53 +0200 Original-Received: from localhost ([::1]:38308 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fO0Eu-00038Z-VI for ged-emacs-devel@m.gmane.org; Wed, 30 May 2018 08:30:04 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:34418) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fO0DW-0002BN-NW for emacs-devel@gnu.org; Wed, 30 May 2018 08:28:39 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fO0DV-00074J-OQ for emacs-devel@gnu.org; Wed, 30 May 2018 08:28:38 -0400 Original-Received: from chene.dit.umontreal.ca ([132.204.246.20]:49192) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fO0DR-00073R-S0; Wed, 30 May 2018 08:28:33 -0400 Original-Received: from ceviche.home (lechon.iro.umontreal.ca [132.204.27.242]) by chene.dit.umontreal.ca (8.14.7/8.14.1) with ESMTP id w4UCSrXi023478; Wed, 30 May 2018 08:28:53 -0400 Original-Received: by ceviche.home (Postfix, from userid 20848) id AC7D9660E5; Wed, 30 May 2018 08:28:29 -0400 (EDT) X-NAI-Spam-Flag: NO X-NAI-Spam-Threshold: 5 X-NAI-Spam-Score: 0 X-NAI-Spam-Rules: 2 Rules triggered EDT_SA_DN_PASS=0, RV6297=0 X-NAI-Spam-Version: 2.3.0.9418 : core <6297> : inlines <6664> : streams <1788234> : uri <2649704> X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 132.204.246.20 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:225825 Archived-At: I think this change is misguided: - When reading source code, you get things like: (pcase-defmacro radix-tree-leaf (vpat) "Build a `pcase' pattern that matches radix-tree leaf EXPVAL. VPAT is a `pcase' pattern to extract the value." where the EXPVAL comes out of nowhere - The wording "matches radix-tree leaf EXPVAL" makes it sound like the reader is already familiar with EXPVAL and that we know already that it's a radix-tree leaf, whereas the pattern will have to check if EXPVAL is such a leaf. - In the pcase docstring, EXPVAL refers to the "toplevel" value, so when we say things like 'VAL matches if EXPVAL is `equal' to VAL. it makes it sound like (cons '1 '2) will not match against the value (1 . 2) because EXPVAL is (1 . 2) and '1 is not `equal` to (1 . 2). - The "standard" way to describe a pattern is to say things like (fumble-tree E1 E2) matches fumble-trees E.g. _ matches anything SYMBOL matches anything and binds it to SYMBOL. (guard BOOLEXP) matches if BOOLEXP evaluates to non-nil. (let PAT EXPR) matches if EXPR matches PAT. (and PAT...) matches if all the patterns match. (or PAT...) matches if any of the patterns matches. While it may occasionally be handy to be able to refer to EXPVAL, for example in (app FUN PAT) matches if FUN called on EXPVAL matches PAT. I believe the standard terminology is to say "the target" instead of EXPVAL. For example, I think the patch below would improve the doc. Stefan diff --git a/lisp/emacs-lisp/radix-tree.el b/lisp/emacs-lisp/radix-tree.el index 2491ccea95..6a11977782 100644 --- a/lisp/emacs-lisp/radix-tree.el +++ b/lisp/emacs-lisp/radix-tree.el @@ -196,8 +196,8 @@ radix-tree-prefixes (eval-and-compile (pcase-defmacro radix-tree-leaf (vpat) - "Build a `pcase' pattern that matches radix-tree leaf EXPVAL. -VPAT is a `pcase' pattern to extract the value." + "Pattern which matches a radix-tree leaf. +The pattern VPAT is matched against the leaf's carried value." ;; FIXME: We'd like to use a negative pattern (not consp), but pcase ;; doesn't support it. Using `atom' works but generates sub-optimal code. `(or `(t . ,,vpat) (and (pred atom) ,vpat)))) diff --git a/lisp/emacs-lisp/pcase.el b/lisp/emacs-lisp/pcase.el index fa7b1de8b4..0ba0d75776 100644 --- a/lisp/emacs-lisp/pcase.el +++ b/lisp/emacs-lisp/pcase.el @@ -119,7 +119,7 @@ pcase PATTERN matches. PATTERN can take one of the forms: _ matches anything. - \\='VAL matches if EXPVAL is `equal' to VAL. + \\='VAL matches objects `equal' to VAL. KEYWORD shorthand for \\='KEYWORD INTEGER shorthand for \\='INTEGER STRING shorthand for \\='STRING