[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#56974: 29.0.50; Missing documentation for former subr-x macros
From: |
Philip Kaludercic |
Subject: |
bug#56974: 29.0.50; Missing documentation for former subr-x macros |
Date: |
Fri, 05 Aug 2022 09:19:32 +0000 |
Eli Zaretskii <eliz@gnu.org> writes:
>> From: Philip Kaludercic <philipk@posteo.net>
>> 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:
>From 0d4c3f418d5dcdaa2f2f9c93b7e1fd103a310c62 Mon Sep 17 00:00:00 2001
From: Philip Kaludercic <philipk@posteo.net>
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
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Philip Kaludercic, 2022/08/04
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Eli Zaretskii, 2022/08/04
- bug#56974: 29.0.50; Missing documentation for former subr-x macros,
Philip Kaludercic <=
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Lars Ingebrigtsen, 2022/08/05
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Michael Heerdegen, 2022/08/05
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Lars Ingebrigtsen, 2022/08/06
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Michael Heerdegen, 2022/08/06
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Lars Ingebrigtsen, 2022/08/07
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Philip Kaludercic, 2022/08/09
- bug#56974: 29.0.50; Missing documentation for former subr-x macros, Po Lu, 2022/08/05