[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#34842: 26.1; Alist documentation: let-alist
From: |
Basil L. Contovounesios |
Subject: |
bug#34842: 26.1; Alist documentation: let-alist |
Date: |
Sun, 13 Oct 2019 03:03:07 +0100 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) |
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