Explicit ordering of destructuring bindings

[NoahTheDuke]

As discussed in this ask.clojure.org question, I and others have been confused by the ordering of bindings in destructuring forms. There is subtle and implied descriptions of the ordering in the Special Forms: Binding Forms page, but I think it could be helpful to make it much more explicit.

The given example on that page shows it but this specific aspect is not obvious by the number of features being shown at once. Maybe splitting it up into individual examples could be helpful.

[puredanger]

Isn't this "an :as key in the binding form followed by a symbol binds that symbol to the entire init-expr" already explicit?

[puredanger]

I think the existing reference is explicit about what :as does (binds the init-expr) and what :or does (supply default values if they are not found in the init-expr). No feature described here implies that init-expr is modified. The semantics of these two features are not order dependent (obviously the implementation has some order, but as nothing modifies init-expr, this is not important). Additionally, the example immediately following covers the case of :or and :as being used together and demonstrates that providing an :or default does not change the init-expr bound by :as. So, I think the existing text covers everything already.

Also, there are additional examples in the destructuring guide https://clojure.org/guides/destructuring.