bug#49407: Request: Specify default values in `map-let` in Map.el

[Michael Heerdegen]

"Basil L. Contovounesios" via "Bug reports for GNU Emacs, the Swiss army
knife of text editors" <bug-gnu-emacs@gnu.org> writes:

> WFM, thank you!  Installed and closing as done:
>
> Allow default values in 'map-let' and the pcase 'map' form
> 19777b7c864 2023-07-30 15:20:27 +0200
> https://git.sv.gnu.org/cgit/emacs.git/commit/?id=19777b7c864

Does this addition look appropriate?

From b2b6f34c08c17a9411c4264ea500b434c833ec04 Mon Sep 17 00:00:00 2001
From: Michael Heerdegen <michael_heerdegen@web.de>
Date: Tue, 25 Jul 2023 20:38:46 +0200
Subject: [PATCH] ; Docstring tweaks in map.el

* lisp/emacs-lisp/map.el (pcase-defmacro) <map>:
(map-let): Mention 'map-elt' where equality predicates are explained.
Improve wording.
---
 lisp/emacs-lisp/map.el | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/lisp/emacs-lisp/map.el b/lisp/emacs-lisp/map.el
index b55eb431668..04c00a2e908 100644
--- a/lisp/emacs-lisp/map.el
+++ b/lisp/emacs-lisp/map.el
@@ -57,9 +57,10 @@ map
 defaults to nil.  Both KEY and DEFAULT are evaluated.

 Each element can also be a SYMBOL, which is an abbreviation of
-a (KEY PAT) tuple of the form (\\='SYMBOL SYMBOL).  When SYMBOL
-is a keyword, it is an abbreviation of the form (:SYMBOL SYMBOL),
-useful for binding plist values.
+a (KEY PAT) tuple of the form (\\='SYMBOL SYMBOL).  A keyword :FOO
+is an abbreviation of the form (:FOO FOO), useful for binding plist values.
+
+See `map-elt' for an explanation of the used equality tests.

 An element of ARGS fails to match if PAT does not match the
 associated value or the default value.  The overall pattern fails
@@ -70,13 +71,13 @@ map
 (defmacro map-let (keys map &rest body)
   "Bind the variables in KEYS to the elements of MAP then evaluate BODY.

-KEYS can be a list of symbols, in which case each element will be
-bound to the looked up value in MAP.
-
-KEYS can also be a list of (KEY VARNAME [DEFAULT]) sublists, in
-which case KEY and DEFAULT are unquoted forms.
+Elements of the list KEYS can be symbols, in which case each
+will be bound to the looked up value in MAP, or
+(KEY VARNAME [DEFAULT]) sublists where KEY and DEFAULT are
+unquoted forms.

-MAP can be an alist, plist, hash-table, or array."
+MAP can be an alist, plist, hash-table, or array.  See `map-elt'
+for an explanation of the used equality tests."
   (declare (indent 2)
            (debug ((&rest &or symbolp ([form symbolp &optional form]))
                    form body)))
--
2.30.2


If it's not clear: I changed :SYMBOL to :FOO because the original text
called SYMBOL a keyword and then used SYMBOL and :SYMBOL (although then
only :SYMBOL would be the keyword) - I found that confusing.  :KEYWORD
would also be confusing, so I went with the placeholder "FOO".

TIA,

Michael.