bug#34842: 26.1; Alist documentation: let-alist

[Basil L. Contovounesios]

Lars Ingebrigtsen <larsi@gnus.org> writes:

> Sebastián Monía <seb.hoagie@outlook.com> writes:
>
>> The macro let-alist is too useful to work with JSON-parsed data for it to be
>> missing from the docs.
>>
>> In the page
>> https://www.gnu.org/software/emacs/manual/html_node/elisp/Association-Lists.html
>> we should add some documentation about it. Below a suggestion.
>>
>> Thank you!
>>
>> — Macro: let-alist `value`
>> Creates a binding for each symbol in the association list `value`, prefixed 
>> with
>> dot. This is very useful when accessing several items in the same alist, and 
>> it's
>> best understood through a simple example:
>>
>> (setq colors '((rose red) (lily white) (buttercup yellow)))
>> (let-alist colors
>>     (print .rose)
>>     (print .buttercup))
>>     ⇒ red
>>     ⇒ yellow
>
> Even though I question the usefulness of this macro (especially since it
> doesn't nest well, so it seems just kinda ad-hoc), I've now documented
> it along the lines you suggest.  Drew wanted the manual to describe more
> fully the actual details behind the implementation, but I think that
> doesn't add much clarity.

Thanks.  The following constitute what I think are some opportunities
for clarifying the current doc.  WDYT?

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index c06e95640d..00c2211c36 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -1781,39 +1781,51 @@ Association Lists
 @sc{car}.
 @end defun
 
-@defmac let-alist alist body
-Creates a binding for each symbol used as keys the association list
-@var{alist}, prefixed with dot.  This can be useful when accessing
-several items in the same association list, and it's best understood
-through a simple example:
+@defmac let-alist alist body@dots{}
+This macro sets up a local binding for each variable that is used in
+@var{body} and whose name starts with a dot, and then evaluates
+@var{body}.  In each case the dot-prefixed variable is bound to the
+value associated with its dot-less suffix in the association list
+@var{alist}.
+
+This can be convenient when accessing several items in the same
+association list, and is best understood through a simple example:
 
 @lisp
 (setq colors '((rose . red) (lily . white) (buttercup . yellow)))
 (let-alist colors
   (if (eq .rose 'red)
       .lily))
-=> white
+     @result{} white
 @end lisp
 
-The @var{body} is inspected at compilation time, and only the symbols
-that appear in @var{body} with a @samp{.} as the first character in
-the symbol name will be bound.  Finding the keys is done with
-@code{assq}, and the @code{cdr} of the return value of this
-@code{assq} is assigned as the value for the binding.
+The @var{body} is inspected at compilation time, and only those
+variables that appear in @var{body} and whose name starts with a
+@samp{.} are bound.  Each such @var{.symbol} is bound to the @sc{cdr}
+of the first association for @var{symbol} in @var{alist} using
+@code{assq}.  If no such association exists, @var{.symbol} is bound to
+@code{nil}:
 
-Nested association lists is supported:
+@lisp
+(let-alist colors
+  .tulip)
+     @result{} nil
+@end lisp
+
+Nested association lists are also supported by concatenating multiple
+dot-prefixed symbols:
 
 @lisp
 (setq colors '((rose . red) (lily (belladonna . yellow) (brindisi . pink))))
 (let-alist colors
   (if (eq .rose 'red)
       .lily.belladonna))
-=> yellow
+     @result{} yellow
 @end lisp
 
-Nesting @code{let-alist} inside each other is allowed, but the code in
-the inner @code{let-alist} can't access the variables bound by the
-outer @code{let-alist}.
+Nesting @code{let-alist} inside calls to itself is allowed, but the
+@var{body} of the inner @code{let-alist} can't access the bindings set
+up by the outer @code{let-alist}.
 @end defmac
 
 @node Property Lists

-- 
Basil