From: "Basil L. Contovounesios" <contovob@tcd.ie>
To: Lars Ingebrigtsen <larsi@gnus.org>
Cc: 34842@debbugs.gnu.org, "Sebastián Monía" <seb.hoagie@outlook.com>
Subject: bug#34842: 26.1; Alist documentation: let-alist
Date: Sun, 13 Oct 2019 03:03:07 +0100 [thread overview]
Message-ID: <871rvh9zc4.fsf@tcd.ie> (raw)
In-Reply-To: <87eezhh763.fsf@gnus.org> (Lars Ingebrigtsen's message of "Sun, 13 Oct 2019 01:32:04 +0200")
[-- Attachment #1: Type: text/plain, Size: 1276 bytes --]
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?
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: let-alist.diff --]
[-- Type: text/x-diff, Size: 2577 bytes --]
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
[-- Attachment #3: Type: text/plain, Size: 11 bytes --]
--
Basil
next prev parent reply other threads:[~2019-10-13 2:03 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-03-13 14:16 bug#34842: 26.1; Alist documentation: let-alist Sebastián Monía
2019-03-13 15:16 ` Drew Adams
2019-03-13 16:30 ` Sebastián Monía
2019-03-13 17:51 ` Drew Adams
2019-03-14 4:47 ` Sebastián Monía
2019-10-12 23:32 ` Lars Ingebrigtsen
2019-10-13 2:03 ` Basil L. Contovounesios [this message]
2019-10-13 2:48 ` Lars Ingebrigtsen
2019-10-13 7:15 ` Eli Zaretskii
2019-10-13 12:38 ` Basil L. Contovounesios
2019-10-13 13:15 ` Eli Zaretskii
2019-10-13 12:17 ` Basil L. Contovounesios
2019-10-13 17:39 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=871rvh9zc4.fsf@tcd.ie \
--to=contovob@tcd.ie \
--cc=34842@debbugs.gnu.org \
--cc=larsi@gnus.org \
--cc=seb.hoagie@outlook.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.