Document destructuring of singleton map sequences

[lassemaatta]

Since clojure 1.11 (as per CLJ-2603), destructuring a sequence containing a single map can directly bind to the map contents. An example of this can be seen here. It might be a good idea to mention this in the destructuring guide as this behaviour might be surprising to some (at least it was for me).

[NoahTheDuke]

here are some relevant threads on clojurian slack highlighting the confusion:

https://clojurians.slack.com/archives/C03S1KBA2/p1668533720466509

https://clojurians.slack.com/archives/C03S1KBA2/p1707982404402549

https://clojurians.slack.com/archives/C03S1KBA2/p1714580544135239

https://clojurians.slack.com/archives/C03S1KBA2/p1715935559111129

[onetom]

I just tripped over this issue today too.

i thought it's a bug, but @puredanger said it's intended behaviour:
https://ask.clojure.org/index.php/12374/map-destructuring-works-on-singleton-lists?show=12380#c12380

so the Destructuring in Clojure guide should definitely mention these peculiarities!

it provides this example:

(defn configure [val & {:keys [debug verbose]
                        :or {debug false, verbose false}}]
  (println "val =" val " debug =" debug " verbose =" verbose))

so it should mention how it behaves the same way, as a function defined as:

(defn configure [val {:keys [debug verbose]
                      :or {debug false, verbose false}}]
  (println "val =" val " debug =" debug " verbose =" verbose))

when called as (configure 12 (list :debug true)) or (configure 12 (list {:debug true})),
but not equivalent, when called as (configure 12 (vector :debug true)) or (configure 12 (vector {:debug true})).

im not sure what reasoning can be given for this behaviour though...

Pondering

given this situation:

(let [m {:x 1}
        {itself :x} m
        {from-list :x} (list m)
        {from-list-of-2 :x} (list m m)
        {from-vector :x} (vector m)]
    [(= itself from-list)
     (nil? from-list-of-2)
     (not= from-list from-vector)])

i'd say (= itself from-list) is surprising.

(nil? from-list-of-2) looks like magic.

(not= from-list from-vector) can easily result in hard to understand errors,
since all u need is to realize some lazy sequence, by spilling it into a vector with vec or (into [] ,,,), instead of doall
and BAMM your program might blow up at a distance.

in my specific situation the behaviour was even more magical, because i had function with an optional argument after the map destructuring one: (fn [arg1 {:as arg2 k :some/k} & [arg3]] ,,,), yet it behaved like (fn [arg1 & {:as arg2 k :some/k}] ,,,), which is apparently the same as (fn [arg1 {:as arg2 k :some/k}] ,,,), when called with a map or a list of a single map.