Document examples of regex-nav.

List-of-Navigators.md

@@ -998,29 +998,52 @@ nil
 
 `(regex-nav regex)`
 
-Uses `re-seq` for selects and `clojure.string/replace` for transforms.
+_Added in 1.0.5_
 
+When supplied with a regex, navigates to every match in a string, and supports replacement with a new substring.
+
+Here are some basic examples of selecting:
 ```clojure
 => (select (regex-nav #"t") "test")
 ["t" "t"]
 => (select [:a (regex-nav #"t")] {:a "test"})
 ["t" "t"]
+```
+
+You can use more advanced features of regexes like capture groups:
+
+```clojure
+=> (select [(regex-nav #"(\S+):\ (\d+)") (nthpath 2)] "Mary: 1st George: 2nd Arthur: 3rd")
+["1" "2" "3"]
+```
+
+You can replace matches with a provided value:
+
+```clojure
+=> (setval (regex-nav #"t") "z" "test")
+"zesz"
+=> (setval [:a (regex-nav #"t")] "z" {:a "test"})
+{:a "zesz"}
+```
+
+Or you can `transform` with a function, such as the ones in the `clojure.string` namespace:
+
+```clojure
 => (transform (regex-nav #"t") clojure.string/capitalize "test")
 "TesT"
 => (transform [:a (regex-nav #"t")] clojure.string/capitalize {:a "test"})
 {:a "TesT"}
 => (transform (regex-nav #"\s+\w") clojure.string/triml "Hello      World!")
 "HelloWorld!"
-=> (setval (regex-nav #"t") "z" "test")
-"zesz"
-=> (setval [:a (regex-nav #"t")] "z" {:a "test"})
-{:a "zesz"}
+```
+
+However, you can also provide your own function, so long as it takes and returns patterns, characters, or strings:
+
+```clojure
 => (transform (regex-nav #"aa*") (fn [s] (-> s count str)) "aadt")
 "2dt"
 => (transform (regex-nav #"[Aa]+") (fn [s] (apply str (take (count s) (repeat "@")))) "Amsterdam Aardvarks")
 "@msterd@m @@rdv@rks"
-=> (select [(regex-nav #"(\S+):\ (\d+)") (nthpath 2)] "Mary: 1st George: 2nd Arthur: 3rd")
-["1" "2" "3"]
 => (transform (subselect (regex-nav #"\d\w+")) reverse "Mary: 1st George: 2nd Arthur: 3rd")
 "Mary: 3rd George: 2nd Arthur: 1st"
 ```