From 4ccc45b6295a1bd30363f50adb1e1b371d251013 Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Thu, 24 Oct 2024 12:10:09 +0800 Subject: [PATCH] Update special conditionals documentation * doc/lispref/control.texi (Conditionals): Document if-let* and when-let*, not if-let and when-let. Document and-let*. (cherry picked from commit eae798486a965ec176bef3cc343625c164986c3f) --- doc/lispref/control.texi | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/doc/lispref/control.texi b/doc/lispref/control.texi index 399b7ee562d..b996a372e28 100644 --- a/doc/lispref/control.texi +++ b/doc/lispref/control.texi @@ -313,30 +313,41 @@ to make this easier and more readable. The above can be written the following way instead: @example -(when-let ((result1 (do-computation)) - (result2 (do-more result1))) +(when-let* ((result1 (do-computation)) + (result2 (do-more result1))) (do-something result2)) @end example There's a number of variations on this theme, and they're briefly described below. -@defmac if-let spec then-form else-forms... -Evaluate each binding in @var{spec} in turn, like in @code{let*} +@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}. @end defmac -@defmac when-let spec then-forms... -Like @code{if-let}, but without @var{else-forms}. +@defmac when-let* varlist then-forms... +Like @code{if-let*}, but without @var{else-forms}. +@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-nil, 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 +Like @code{when-let*}, but repeat until a binding in @var{spec} is @code{nil}. The return value is always @code{nil}. @end defmac +Some Lisp programmers follow the convention that @code{and} and +@code{and-let*} are for forms evaluated for return value, and +@code{when} and @code{when-let*} are for forms evaluated for side-effect +with returned values ignored. + @node Combining Conditions @section Constructs for Combining Conditions @cindex combining conditions -- 2.39.5