Re: Is this a bug in while-let or do I missunderstand it?

[Joost Kremers <joostkremers@fastmail.fm>]

[-- Attachment #1: Type: text/plain, Size: 2028 bytes --]

On Thu, Nov 14 2024, Joost Kremers wrote:
> On Thu, Nov 14 2024, Eli Zaretskii wrote:
>>> From: Joost Kremers <joostkremers@fastmail.fm>
>>> I ended up putting it in the description of the first macro (`if-let*`) and
>>> referring to it in the others, because the relevant variable (here SPEC) is
>>> actually called VARLIST in `if-let*`, `when-let*` and `and-let*`, but SPEC
>>> in while-let. (The non-starred versions also have SPEC, but they're being
>>> deprecated. BTW, any reason why `while-let` isn't called `while-let*`?)
>>
>> The disadvantage of what you did is that you need to say repeatedly
>>
>>   @var{varlist} has the same form as in @code{if-let*}.
>>
>> and the reader has to go back, read the description of if-let* (which
>> she might not want to know anything about), and decide which parts of
>> that description are relevant to whatever macro she is interested in.
>
> Okay, so I'll put the explanation of VARLIST into the description of every
> macro.
>

Here's the new patch (finally...) `when-let*`, `and-let*` and `while-let`
now have an additional paragraph saying:

```
@var{varlist} has the same form as in @code{if-let*}: Each element of
@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}}, in
which @var{value-form} is evaluated and @var{symbol} is locally bound to
the result. Bindings are sequential, as in @code{let*} (@pxref{Local
Variables}). As a special case, @var{symbol} can be omitted if only the
test result of @var{value-form} is of interest: @var{value-form} is
evaluated and checked for @code{nil}, but its value is not bound. ```

I agree this is better when you only want to read up on a single macro, but
it's arguably less pretty when you're reading through the entire section,
having to read the same thing four times... For that case, I pointed out
that VARLIST is the same as for `if-let*`, so a reader knows they can skip
that paragraph and won't have to wonder if there are subtle differences
between the macros.

-- 
Joost Kremers
Life has its moments


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Improve-documentation-for-while-let.patch --]
[-- Type: text/x-patch, Size: 4790 bytes --]

From 5ff93bf0652cd3c409e08c4d521945c6ca60c207 Mon Sep 17 00:00:00 2001
From: Joost Kremers <joostkremers@fastmail.com>
Date: Mon, 11 Nov 2024 23:38:49 +0100
Subject: [PATCH] Improve documentation for `while-let'.

* doc/lispref/control.texi: Improve documentation for `while-let`.
---
 doc/lispref/control.texi | 64 +++++++++++++++++++++++++++++++++-------
 1 file changed, 53 insertions(+), 11 deletions(-)

diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi
index 80ed2ce899b..a05e4d81fda 100644
--- a/doc/lispref/control.texi
+++ b/doc/lispref/control.texi
@@ -322,25 +322,46 @@ Conditionals
 described below.
 
 @defmac if-let* varlist then-form else-forms...
-Evaluate each binding in @var{varlist} in turn, like in @code{let*}
-(@pxref{Local Variables}), stopping if a binding value is @code{nil}.
-If all are non-@code{nil}, return the value of @var{then-form},
-otherwise the last form in @var{else-forms}.
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of
+@var{then-form}, otherwise the last form in @var{else-forms}.
+
+Each element of @code{varlist} has the form @w{@code{(@var{symbol}
+@var{value-form})}}: @var{value-form} is evaluated and @var{symbol} is
+locally bound to the result.  Bindings are sequential, as in @code{let*}
+(@pxref{Local Variables}).  As a special case, @var{symbol} can be
+omitted if only the test result of @var{value-form} is of interest:
+@var{value-form} is evaluated and checked for @code{nil}, but its value
+is not bound.
 @end defmac
 
 @defmac when-let* varlist then-forms...
-Like @code{if-let*}, but without @var{else-forms}.
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of the last
+form in @var{then-forms}.
+
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which @var{value-form} is evaluated and @var{symbol} is locally bound
+to the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
 @end defmac
 
 @defmac and-let* varlist then-forms...
-Like @code{when-let*}, but in addition, if there are no
-@var{then-forms} and all the bindings evaluate to non-@code{nil}, return
+Evaluate each binding in @var{varlist}, stopping if a binding value is
+@code{nil}.  If all are non-@code{nil}, return the value of the last
+form in @var{then-forms}, or, if there are no @var{then-forms}, return
 the value of the last binding.
-@end defmac
 
-@defmac while-let spec then-forms...
-Like @code{when-let*}, but repeat until a binding in @var{spec} is
-@code{nil}.  The return value is always @code{nil}.
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which @var{value-form} is evaluated and @var{symbol} is locally bound
+to the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
 @end defmac
 
 Some Lisp programmers follow the convention that @code{and} and
@@ -348,6 +369,27 @@ Conditionals
 @code{when} and @code{when-let*} are for forms evaluated for side-effect
 with returned values ignored.
 
+A similar macro exists to run a loop until one binding evaluates to
+@code{nil}:
+
+@defmac while-let spec then-forms...
+Evaluate each binding in @var{spec} in turn, stopping if a binding value
+is @code{nil}.  If all are non-@code{nil}, execute @var{then-forms},
+then repeat the loop.  Note that when the loop is repeated, the
+@var{value-forms} in @var{spec} are re-evaluated and the bindings are
+established anew.
+
+@var{varlist} has the same form as in @code{if-let*}: Each element of
+@code{varlist} has the form @w{@code{(@var{symbol} @var{value-form})}},
+in which {value-form} is evaluated and @var{symbol} is locally bound to
+the result.  Bindings are sequential, as in @code{let*} (@pxref{Local
+Variables}).  As a special case, @var{symbol} can be omitted if only the
+test result of @var{value-form} is of interest: @var{value-form} is
+evaluated and checked for @code{nil}, but its value is not bound.
+
+The return value of @code{while-let} is always @code{nil}.
+@end defmac
+
 @node Combining Conditions
 @section Constructs for Combining Conditions
 @cindex combining conditions
-- 
2.47.0