From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Philip Kaludercic Newsgroups: gmane.emacs.bugs Subject: bug#56974: 29.0.50; Missing documentation for former subr-x macros Date: Fri, 05 Aug 2022 09:19:32 +0000 Message-ID: <87a68jjbdn.fsf@posteo.net> References: <87o7x0jgz7.fsf@posteo.net> <83les42lfd.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="34813"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 56974@debbugs.gnu.org To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Aug 05 11:20:20 2022 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1oJtVD-0008tT-JZ for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 11:20:19 +0200 Original-Received: from localhost ([::1]:42352 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1oJtVC-0002bA-Br for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 05 Aug 2022 05:20:18 -0400 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:46102) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1oJtUw-0002av-Nb for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 05:20:03 -0400 Original-Received: from debbugs.gnu.org ([209.51.188.43]:38194) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1oJtUw-0006Sp-DQ for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 05:20:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1oJtUw-0007M9-9Q for bug-gnu-emacs@gnu.org; Fri, 05 Aug 2022 05:20:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Philip Kaludercic Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 05 Aug 2022 09:20:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 56974 X-GNU-PR-Package: emacs Original-Received: via spool by 56974-submit@debbugs.gnu.org id=B56974.165969119128254 (code B ref 56974); Fri, 05 Aug 2022 09:20:02 +0000 Original-Received: (at 56974) by debbugs.gnu.org; 5 Aug 2022 09:19:51 +0000 Original-Received: from localhost ([127.0.0.1]:56176 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJtUl-0007Le-2x for submit@debbugs.gnu.org; Fri, 05 Aug 2022 05:19:51 -0400 Original-Received: from mout01.posteo.de ([185.67.36.65]:55005) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1oJtUf-0007LI-Uc for 56974@debbugs.gnu.org; Fri, 05 Aug 2022 05:19:49 -0400 Original-Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id E54CA240027 for <56974@debbugs.gnu.org>; Fri, 5 Aug 2022 11:19:37 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1659691179; bh=A5WMFFIy4yGgAv5TCgXSg/x4Zi6+2Zc7mIFMKO/Pe7Q=; h=From:To:Cc:Subject:Autocrypt:Date:From; b=RgorE3BLQAMsnyA556qyVHDPdBW5g5GzFkGKjsRvI3oRCi6Nc1KNhqHng85mC1m+o yG76Qac7bhiFOTKFQsAaP1CBzrttCCjaQIuv8/7AH67LLaBW+MMc6kCQJsPqw71xEu ivH+IKt/OgHEIIrADvZFb86L4oMn/RF4ApOOQaVZtth8bcjb6ievAppXCrFx6tCPzD i9iumJfd3J3L3kJi+Wrc78p3uujcc322FUHHF2APXqJhSx3f+X0aoIsnMXPfNYzgXA F/R3Cnw/YYIseoVeBMvJ/adAKjL8y7LtWTubWDI9A0iIPs7ANPkJSyrygTGEMDQO4L MkDnXGjDFShCA== Original-Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4Lzg605bLBz6tmR; Fri, 5 Aug 2022 11:19:34 +0200 (CEST) In-Reply-To: <83les42lfd.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 04 Aug 2022 16:22:14 +0300") Autocrypt: addr=philipk@posteo.net; prefer-encrypt=nopreference; keydata= mDMEYHHqUhYJKwYBBAHaRw8BAQdAp3GdmYJ6tm5McweY6dEvIYIiry+Oz9rU4MH6NHWK0Ee0QlBo aWxpcCBLYWx1ZGVyY2ljIChnZW5lcmF0ZWQgYnkgYXV0b2NyeXB0LmVsKSA8cGhpbGlwa0Bwb3N0 ZW8ubmV0PoiQBBMWCAA4FiEEDM2H44ZoPt9Ms0eHtVrAHPRh1FwFAmBx6lICGwMFCwkIBwIGFQoJ CAsCBBYCAwECHgECF4AACgkQtVrAHPRh1FyTkgEAjlbGPxFchvMbxzAES3r8QLuZgCxeAXunM9gh io0ePtUBALVhh9G6wIoZhl0gUCbQpoN/UJHI08Gm1qDob5zDxnIHuDgEYHHqUhIKKwYBBAGXVQEF AQEHQNcRB+MUimTMqoxxMMUERpOR+Q4b1KgncDZkhrO2ql1tAwEIB4h4BBgWCAAgFiEEDM2H44Zo Pt9Ms0eHtVrAHPRh1FwFAmBx6lICGwwACgkQtVrAHPRh1Fw1JwD/Qo7kvtib8jy7puyWrSv0MeTS g8qIxgoRWJE/KKdkCLEA/jb9b9/g8nnX+UcwHf/4VfKsjExlnND3FrBviXUW6NcB X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list 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-mx.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.io gmane.emacs.bugs:238846 Archived-At: --=-=-= Content-Type: text/plain Eli Zaretskii writes: >> From: Philip Kaludercic >> Date: Thu, 04 Aug 2022 13:06:20 +0000 >> >> >> As far as I see, if-let, when-let, thread-first, ... were moved from >> subr-x.el to subr.el last April (b05a103e). But there appears to be no >> documentation in (I'd assume) lispref/controls.texi. My understanding >> was that these macros were not documented in the Elisp manual as they >> were just part of subr-x, as the comment in the subr-x header indicates >> >> ;; Do not document these functions in the lispref. >> ;; https://lists.gnu.org/r/emacs-devel/2014-01/msg01006.html >> >> So should they be documented now? > > Yes, they should be. How is this for a start: --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-Document-if-let-if-let-when-let-and-and-let.patch >From 0d4c3f418d5dcdaa2f2f9c93b7e1fd103a310c62 Mon Sep 17 00:00:00 2001 From: Philip Kaludercic Date: Fri, 5 Aug 2022 11:18:29 +0200 Subject: [PATCH] Document if-let*, if-let, when-let* and and-let* * control.texi (Conditionals): Add if-let*, if-let, when-let* (Combining Conditions): Add and-let* --- doc/lispref/control.texi | 47 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index d4520ebdee..e7fd1bb41a 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -294,6 +294,46 @@ Conditionals @end group @end example +During complex computations that might at any step, one can combine a +@code{let}-block and some of the previous conditional control +structures: + +@defmac if-let (bindings@dots) then &rest else@dots +As with @code{let*}, @var{bindings} will consist of +@code{(@var{symbol} @var{value-form})} entries that are evaluated and +bound sequentially. If all @var{value-form} evaluate to +non-@code{nil} values, then @var{then} is evaluated as were the case +with a regular @code{let*} expression, with all the variables bound. +If any @var{value-form} evaluates to @code{nil}, @var{else} is +evaluated, without any bound variables. + +A binding may also optionally drop the @var{symbol}, and simplify to +@code{(@var{value-form})} if only the test is of interest. + +For the sake of backwards compatibility, it is possible to write a +single binding without a binding list: + +@example +@group +(if-let* (@var{symbol} (test)) foo bar) +@equiv{} +(if-let* ((@var{symbol} (test))) foo bar) +@end group +@end example +@end defmac + +@defmac if-let* (bindings@dots) then &rest else +@code{if-let*} is mostly equivalent to @code{if-let}, with the +exception that the legacy @code{(if (@var{var} (test)) foo bar)} +syntax is not permitted. +@end defmac + +@defmac when-let (bindings@dots) &rest body +As with @code{when}, if one is only interested in the case where all +@var{bindings} are non-nil. Otherwise @var{bindings} are interpreted +just as they are by @code{if-let*}. +@end defmac + @node Combining Conditions @section Constructs for Combining Conditions @cindex combining conditions @@ -428,6 +468,13 @@ Combining Conditions Note that in contrast to @code{or}, both arguments are always evaluated. @end defun +@defmac and-let* (bindings@dots) &rest body +A combination of @var{let*} and @var{and}, analogous to +@code{when-let*}. If all @var{bindings} are non-@code{nil} and +@var{body} is @code{nil}, then the result of the @code{and-let*} form +will be the last value bound in @var{bindings}. +@end defmac + @node Pattern-Matching Conditional @section Pattern-Matching Conditional @cindex pcase -- 2.37.1 --=-=-=--