refining language

Author: fogus

content/guides/destructuring.adoc

@@ -273,9 +273,9 @@ Associative destructuring, however, also allows you to supply a default value if
 ;= Category not found
 ----
 
-The value for `:or` is a map where the bound symbol (here `category`) is bound to the expression `"Category not found"`. When category is not found in `client`, it is instead found in the `:or` map and bound to that value instead. When used this way, the default is for the key associated with that binding name. If you haven't yet used that binding name in a binding elsewhere, it is not associated with any key and the entry is a no-op.
+To supply default values for keys that are not present in the input map, you can use the `:or` directive, whose value is a map of binding names or [since 1.13] keys to default values. Thus here `"Category not found"` will be used as the value for the binding category if the key `:category` is not in the input map (`client`). Note that if an unadorned symbol is used as a key in the `:or` map but not yet in any binding the entry is a no-op.
 
-You may also specify values either via explicit keys in the `:or` map, which was added in Clojure 1.13.
+The next example uses `:category` as an explicit key rather than the binding name `category` in the `:or` map.
 
 [source,clojure]
 ----
@@ -284,7 +284,7 @@ You may also specify values either via explicit keys in the `:or` map, which was
 ;= "Category again not found"
 ----
 
-If you wish to capture the default values stated in the `:or` map, the `:defaults` directive, added in Clojure 1.13, binds a name to a map, created during destructuring, of keys to their default values. You would use `:defaults` when you want those same default values for some purpose later in your code, and don't want to restate them.
+If you wish to capture the default values stated in the `:or` map, the `:defaults` directive binds a name to a map, created during destructuring, of keys to their default values. [since 1.13] You would use `:defaults` when you want those same default values for some purpose later in your code, and don't want to restate them.
 
 [source,clojure]
 ----
@@ -304,7 +304,7 @@ If you need access to the entire map, you can use the `:as` key to bind the enti
 ;= The name from {:name Super Co., :location Philadelphia, :description The world wide leader in plastic table-ware.} is Super Co.
 ----
 
-The `:as`, `:or`, and `:defaults` keywords can be combined in a single destructuring.
+The `:as`, `:or`, and `:defaults` keywords can be combined in a single destructuring form:
 
 [source,clojure]
 ----
@@ -346,7 +346,7 @@ The `:keys` key is for associative values with keyword keys, but there are also
 ;= Jane Doe
 ----
 
-Additionally, since Clojure 1.13 there are checked versions of the binding directives named `:keys!`, `:strs!`, and `:syms!` that throw an exception if the keys specified are not present in the destructured map.
+If you want it to be an error to supply a map that is missing certain keys (rather than get `nil` or default values), you can [since 1.13] use the checked versions of the binding directives  (`:keys!`, `:strs!`, and `:syms!`) that throw an exception if the required keys are not present.
 
 [source,clojure]
 ----
@@ -355,20 +355,20 @@ Additionally, since Clojure 1.13 there are checked versions of the binding direc
 ;= throws Missing required key: "dob"
 ----
 
-As of Clojure 1.13, all of the binding directives allow you to specify literal keys after `&` for documentation:
+If you have keys you want to require but don't need to bind, you can list them after `&`, which will check for the presence of the listed keys but not create bindings.
 
 [source,clojure]
 ----
-(let [{:keys [fred ethel lucy & :ricky]} m] ...
+(let [{:keys! [fred ethel lucy & :ricky]} m] ...
 
-(let [{:strs [fred ethel lucy & "ricky"]} m] ...
+(let [{:strs! [fred ethel lucy & "ricky"]} m] ...
 
-(let [{:syms [fred ethel lucy & 'ricky]} m] ...
+(let [{:syms! [fred ethel lucy & 'ricky]} m] ...
 ----
 
-The use of `&` in the unchecked versions allow you to specify accepted keys, but its use in the checked variants is more strict as the keys specified are still required and will throw if not present.
+You can also document additional optional keys that you are not binding in the (:keys, :strs, and :syms) directives using `&`. [since 1.13]
 
-Also added in Clojure 1.13 is a new 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.
+To bind a name to a deep subset of the input map, augmented by defaults, use the `:select` directive. [since 1.13] It includes every key used anywhere in the destructuring form, including nested forms, but not keys used only in `:or`.
 
 [source,clojure]
 ----
@@ -399,21 +399,6 @@ Associative destructuring can be nested and combined with sequential destructuri
 ;= Joe is a Ranger wielding a Longbow
 ----
 
-With nested destructuring, the use of `:or`, `:defaults`, and `:select` only apply at the level at which they are applied:
-
-[source,clojure]
-----
-(let [{{:keys [class weapon name], :or {:name "Sir Joe"}, :defaults jdf, :select joe} :joe
-       npc :npc
-       :or {npc {:class "Farmer", :weapon "Shovel"}}} multiplayer-game-state]
-  (println "Joe's :select data is" joe)
-  (println name "had his name set as a default from the :or map" jdf)
-  (println "The default unnamed NPC is" npc))
-;= Joe's :select data is {:weapon "Longbow", :name "Sir Joe", :class "Ranger"}
-;= Sir Joe had his name set as a default from the :or map {:name "Sir Joe"}
-;= The default unnamed NPC is {:class "Farmer", :weapon "Shovel"}
-----
-
 === Keyword arguments
 
 One special case is using associative destructuring for keyword-arg parsing. Consider a function that takes options `:debug` and `:verbose`. These could be specified in an options map:

content/reference/special_forms.adoc

@@ -296,7 +296,7 @@ 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:
+The `:or` maps also accept the input key directly in place of the binding name. [since 1.13]
 
 [source,clojure]
 ----
@@ -306,7 +306,7 @@ Since Clojure 1.13, the `:or` directive also allows the use of explicit keys:
 ->[5 3 42 {: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:
+To capture the `:or` defaults as a map bound to a name, use the `:defaults` directive. [since 1.13]
 
 [source,clojure]
 ----
@@ -352,14 +352,7 @@ In the case of using prefixed keys, the bound symbol name is the same as the rig
 -> 42
 ----
 
-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] ...
-----
-
-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.
+There are similar `:strs` and `:syms` directives for matching string and symbol keys, the latter also allowing prefixed symbol keys. 
 
 Clojure 1.9 adds support for directly destructuring many keys (or symbols) that share the same namespace using the following destructuring key forms:
 
@@ -379,14 +372,16 @@ 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` binding directives - `:keys!`/`:syms!`/`:strs!`, which will throw an exception if the keys specified are not present in the destructured map. These checked directives also support the use of `&` and will check the presence of the specified keys in the destructured map.
+You can ensure that required keys are present during map destructuring by using the checked variants of the `:keys`/`:syms`/`:strs` binding directives named `:keys!`/`:syms!`/`:strs!`, which throw an exception if any of the specified keys are missing from the destructured map. [since 1.13] These checked directives also accept `&`, after which you may list additional keys that are still required and checked, but not bound to a local name.
 
 [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.
+The literal keys after `&` for these directives should 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. In the unchecked directives `:keys`, `:strs`, and `:syms`, `&` serves only as documentation: the listed keys are neither bound nor checked for presence. [since 1.13]
+
+To bind a name to a deep subset of the input map, augmented by defaults, use the `:select` directive. [since 1.13] It includes every key used anywhere in the destructuring form, including nested forms, but not keys used only in `:or`.
 
 [source,clojure]
 ----