From fa762e809ca6c0973cd593a1063bf44469ed2bf5 Mon Sep 17 00:00:00 2001
From: Michael Fogleman <michaelwfogleman@gmail.com>
Date: Sun, 22 Oct 2017 12:31:53 -0400
Subject: [PATCH 1/3] Initial regex-nav doc.

---
 List-of-Navigators.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/List-of-Navigators.md b/List-of-Navigators.md
index 70513cb..91d29fe 100644
--- a/List-of-Navigators.md
+++ b/List-of-Navigators.md
@@ -68,6 +68,7 @@ It is a convention in Specter that unparameterized navigators are capitalized, w
     - [pred>=](#pred>=)
     - [putval](#putval)
     - [not-selected?](#not-selected)
+    - [regex-nav](#regex-nav)
     - [selected?](#selected)
     - [set-elem](#set-elem)
     - [srange](#srange)
@@ -993,6 +994,37 @@ See also [selected?](#selected?).
 nil
 ```
 
+## regex-nav
+
+`(regex-nav regex)`
+
+Uses `re-seq` for selects and `clojure.string/replace` for transforms.
+
+```clojure
+=> (select (regex-nav #"t") "test")
+["t" "t"]
+=> (select [:a (regex-nav #"t")] {:a "test"})
+["t" "t"]
+=> (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"}
+=> (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"
+```
+
 ## selected?
 
 `(selected? & path)`

From 413d7c52d15cc76e6f6a1c4ea937f797b847bc3c Mon Sep 17 00:00:00 2001
From: Michael Fogleman <michaelwfogleman@gmail.com>
Date: Mon, 23 Oct 2017 08:37:11 -0400
Subject: [PATCH 2/3] Document examples of regex-nav.

---
 List-of-Navigators.md | 37 ++++++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/List-of-Navigators.md b/List-of-Navigators.md
index 91d29fe..55d3ba4 100644
--- a/List-of-Navigators.md
+++ b/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"
 ```

From d1b4e1e6f795b00cd3ddf1a5fb11bcfee45fa9d8 Mon Sep 17 00:00:00 2001
From: Michael Fogleman <michaelwfogleman@gmail.com>
Date: Thu, 16 Nov 2017 20:19:20 -0500
Subject: [PATCH 3/3] Add implicit nav documentation.

---
 List-of-Navigators.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/List-of-Navigators.md b/List-of-Navigators.md
index 55d3ba4..b6b77d0 100644
--- a/List-of-Navigators.md
+++ b/List-of-Navigators.md
@@ -1048,6 +1048,12 @@ However, you can also provide your own function, so long as it takes and returns
 "Mary: 3rd George: 2nd Arthur: 1st"
 ```
 
+Specter also implicitly converts regexes in paths to call regex-nav:
+```clojure
+=> (setval #"t" "z" "test")
+"zesz"
+```
+
 ## selected?
 
 `(selected? & path)`