Adding docs for new :or, :select, and :defaults

Author: fogus

content/reference/special_forms.adoc

@@ -296,6 +296,26 @@ Map __binding-form__s create bindings by looking up values in collections like m
 ->[5 3 6 {:c 6, :a 5}]
 ----
 
+Since Clojure 1.13, the `:or` directive also allows the use of explicit keys:
+
+[source,clojure]
+----
+(let [{a :a, b :b, c :c, :as m :or {a 2 b 3 :c 42}}  {:a 5}]
+  [a b c m])
+
+->[5 3 42 {:c 6, :a 5}]
+----
+
+Also since Clojure 1.13, Clojure allows you to bind a name to a map of keys mapped to their default values, based on what you've said in `:or` per above:
+
+[source,clojure]
+----
+(let [{a :a, b :b, c :c, :as m :or {a 2 b 3 :c 42} :defaults df}  {:a 5}]
+  [a b c df])
+
+->[5 3 42 {:a 2, :b 3, :c 42}]
+----
+
 It is often the case that you will want to bind symbols with the same name as the corresponding map keys. The `:keys` directive addresses the redundancy often found in the binding __binding-form->key__ pairs:
 
 [source,clojure]
@@ -332,14 +352,14 @@ In the case of using prefixed keys, the bound symbol name is the same as the rig
 -> 42
 ----
 
-As of Clojure 1.13, map destructuring directives allow you to specify keys after `&` which will not be bound, but serve as documentation:
+As of Clojure 1.13, associative destructuring directives allow you to specify literal keys after `&` that serve as documentation:
 
 [source,clojure]
 ----
-(let [{:keys [fred ethel lucy & ricky]} m] ... ;; ricky is not bound
+(let [{:keys [fred ethel lucy & :ricky]} m] ...
 ----
 
-There are similar `:strs` and `:syms` directives for matching string and symbol keys, the latter also allowing prefixed symbol keys since Clojure 1.6, and support for `&` since Clojure 1.13.
+There are similar `:strs` and `:syms` directives for matching string and symbol keys, the latter also allowing prefixed symbol keys since Clojure 1.6. The literal keys after `&` for these directives match the form of the keys handled, e.g. `:strs [a & "b"]` and `:syms [a & 'b]`. For `:syms` the use of quote is required to distinguish between a binding name and a literal symbol.
 
 Clojure 1.9 adds support for directly destructuring many keys (or symbols) that share the same namespace using the following destructuring key forms:
 
@@ -359,7 +379,22 @@ Clojure 1.9 adds support for directly destructuring many keys (or symbols) that
 -> [1 2]
 ----
 
-As of Clojure 1.13, you can now ensure that required keys are bound during map destructuring by using the new checked variants of the `:keys`/`:syms`/`:strs` directives - `:keys!`/`:syms!`/`:strs!`, which will throw if the key is not present. Once again, the use of `&` in these checked variants will not bind names, but those keys are still checked in the destructured map.
+As of Clojure 1.13, you can now ensure that required keys are bound during map destructuring by using the new checked variants of the `:keys`/`:syms`/`:strs` directives - `:keys!`/`:syms!`/`:strs!`, which will throw if the key is not present. These checked directives also support the use of `&` and will check the presence of the specified keys in the destructured map.
+
+[source,clojure]
+----
+(let [{:keys! [fred ethel lucy & :ricky]} m] ... ;; m must have keys :fred, :ethel, :lucy, and :ricky
+----
+
+As of Clojure 1.13, supports a directive `:select` that binds a name to a map, created during destructuring, containing only those keys from the input map, or the defaults if not present in the input, that are used anywhere in the destructuring form (other than in `:or`), including in nested destructuring. Thus it is a (deep) subset of the input augmented by defaults.
+
+[source,clojure]
+----
+(let [{:keys [a b & :c] :as m :or {a 42 b 3 :c 4} :select sm :defaults df}  {:a 5}]
+  [a b m sm df])
+
+-> [5 3 {:a 1} {:c 4, :b 3, :a 5} {:a 42, :b 3, :c 4}]
+----
 
 [[keyword-arguments]]
 === Keyword Arguments