mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-06 06:20:55 -08:00
Code Issues Projects Releases Wiki Activity

Improve documentation for 'while-let'

Browse source 
* doc/lispref/control.texi (Conditionals): Reorganise describing
what's overlapping between the macros (and between the macros
and let*), and then improve the documentation for 'while-let'.
This commit is contained in:
Joost Kremers 2024-11-11 23:38:49 +01:00 • committed by Sean Whitton
parent 50b91ed458
commit 3e396b2c5b
1 changed files with 53 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

64
doc/lispref/control.texi
View file

@ -322,25 +322,46 @@ There's a number of variations on this theme, and they're briefly
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 @@ Some Lisp programmers follow the convention that @code{and} and
@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 @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.
The return value of @code{while-let} is always @code{nil}.
@end defmac
@node Combining Conditions
@section Constructs for Combining Conditions
@cindex combining conditions