Describe zip API sub editing in docs

Added a new section to user guide.

Minor updates to docstrings to clarify, recategorize and point to user
guide.

Closes #111

Author: lread

CHANGELOG.adoc

@@ -17,6 +17,7 @@ For a list of breaking changes see link:#v1-breaking[breaking changes].
 === Unreleased
 
 * Beef up docs on node creation https://github.com/clj-commons/rewrite-clj/issues/97[#97]
+* Describe subedit in docs https://github.com/clj-commons/rewrite-clj/issues/111[#111]
 
 === v1.0.579-alpha
 

doc/01-user-guide.adoc

@@ -324,6 +324,112 @@ It offers some functions that correspond to the standard Clojure `seq` functions
 ;; => "{:prefix/a 10 :prefix/b 20}"
 ----
 
+// Targeted from docstrings
+[#sub-editing]
+==== Sub Editing with the Zip API
+
+Sub editing allows you to effect changes to an isolated subtree (actually a sub zipper) while preserving your original location in the zipper
+
+When sub editing, your sub zipper is isolated to the current node and its children.
+The sub zipper acts like, and is, a full zipper; `rewrite-clj.zip/end?` will return `true` when you have navigated to the end of the sub zipper.
+
+This can be useful when you:
+
+* Are not interested in restoring your location after digging down deep to make a change
+* Want to restrict your changes to a node and its children.
+It can be helpful to bound your movement when using functions that also affect current location such as `rewrite-clj.zip/remove`.
+
+[source,Clojure]
+----
+(require '[rewrite-clj.zip :as z])
+
+;; A sample to illustrate
+(def zloc (z/of-string "[a [b [c [d [e [f]]]]] g h]"))
+
+;; ... and a little helper that navigates our location to the end node:
+(defn to-end [zloc]
+  (->> zloc
+       (iterate z/next)
+       (drop-while (complement z/end?))
+       first))
+
+;; ... and a little editor to show which node was hit:
+(defn update-at-loc [zloc]
+  (z/edit zloc #(symbol "UPDATED" (str %))))
+
+;; If we don't use a sub zipper our end node is h:
+(-> zloc
+    to-end
+    update-at-loc
+    z/root-string)
+;; => "[a [b [c [d [e [f]]]]] g UPDATED/h]"
+
+;; If we subedit on the first node in the vector, we are restricted to that node.
+;; In our case that node is a:
+(-> zloc
+    z/down
+    (z/subedit->
+     to-end
+     update-at-loc)
+    z/root-string)
+;; => "[UPDATED/a [b [c [d [e [f]]]]] g h]"
+
+;; If we subedit on the second node in the vector, we are restricted to that node.
+;; In our case that node is [b [c [d [f]]]] with subedit end node f
+(-> zloc
+    z/down
+    z/right
+    (z/subedit->
+     to-end
+     update-at-loc)
+    z/root-string)
+;; => "[a [b [c [d [e [UPDATED/f]]]]] g h]"
+
+;; To show our original location was preserved,
+;; after a subedit of the last node within the 2nd node in the vector,
+;; a movement right brings us to node g
+(-> zloc
+    z/down
+    z/right
+    (z/subedit->
+     to-end
+     (z/edit #(symbol "UPDATED" (str %))))
+    z/right
+    z/string)
+;; => "g"
+----
+
+The zip API walk functions also isolate your work to the current node.
+Let's explore:
+
+[source,Clojure]
+----
+(require '[rewrite-clj.zip :as z])
+
+;; Let's contrive an example with multiple top level forms:
+(def zloc (z/of-string "(def x 1) (def y [2 3 [4 [5]]])"))
+
+;; Now let's add 100 to all numbers:
+(-> zloc
+    (z/postwalk (fn select [zloc] (number? (z/sexpr zloc)))
+                (fn visit [zloc] (z/edit zloc + 100)))
+    z/root-string)
+;; => "(def x 101) (def y [2 3 [4 [5]]])"
+
+;; Hmmm... what happened? Only the first number was affected.
+;; A new zipper automaticaly navigates to the first non-whitespace/non-comment node.
+;; In our example, this is node (def x 1).
+;; Our walk was isolated to current node (def x 1) so that's all that got updated
+
+;; We can adapt to walk all nodes with a movement up to the top level prior to our walk
+(-> zloc
+    z/up
+    (z/postwalk (fn select [zloc] (number? (z/sexpr zloc)))
+                (fn visit [zloc] (z/edit zloc + 100)))
+    z/root-string)
+;; => "(def x 101) (def y [102 103 [104 [105]]])"
+----
+
 // Targeted from docstrings
 [#position-tracking]
 ==== Tracking Position with the Zip API

src/rewrite_clj/zip.cljc

@@ -122,17 +122,19 @@
   [[append-child*]]
   [[remove*]]
 
-  **Isolated update without changing location**
+  **Update without changing location**
   [[edit-node]]
+  [[edit->]]
+  [[edit->>]]
+
+  **Isolated update without changing location**
   [[subedit-node]]
   [[subzip]]
   [[prewalk]]
   [[postwalk]]
-  [[edit->]]
-  [[edit->>]]
   [[subedit->]]
   [[subedit->>]]
-
+ 
   **Sequence operations**
   [[map]]
   [[map-keys]]
@@ -675,44 +677,58 @@
 (defn edit-node
   "Return zipper applying function `f` to `zloc`. The resulting
    zipper will be located at the same path (i.e. the same number of
-   downwards and right movements from the root) incoming `zloc`."
+   downwards and right movements from the root) incoming `zloc`.
+   
+   See also [[subedit-node]] for an isolated edit."
   [zloc f] (rewrite-clj.zip.subedit/edit-node zloc f))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defn subedit-node
   "Return zipper replacing current node in `zloc` with result of `f` applied to said node as an isolated sub-tree.
-   The resulting zipper will be located on the root of the modified sub-tree."
+   The resulting zipper will be located on the root of the modified sub-tree.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc f] (rewrite-clj.zip.subedit/subedit-node zloc f))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defn subzip
-  "Create and return a zipper whose root is the current node in `zloc`."
+  "Create and return a zipper whose root is the current node in `zloc`.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc] (rewrite-clj.zip.subedit/subzip zloc))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defmacro edit->
   "Like `->`, threads `zloc` through forms.
    The resulting zipper will be located at the same path (i.e. the same
-   number of downwards and right movements from the root) as incoming `zloc`."
+   number of downwards and right movements from the root) as incoming `zloc`.
+   
+   See also [[subedit->]] for an isolated edit."
   [zloc & body] `(rewrite-clj.zip.subedit/edit-> ~zloc ~@body))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defmacro edit->>
   "Like `->>`, threads `zloc` through forms.
    The resulting zipper will be located at the same path (i.e. the same
-   number of downwards and right movements from the root) as incoming `zloc`."
+   number of downwards and right movements from the root) as incoming `zloc`.
+   
+   See also [[subedit->>]] for an isolated edit."
   [zloc & body] `(rewrite-clj.zip.subedit/edit->> ~zloc ~@body))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defmacro subedit->
   "Like `->`, threads `zloc`, as an isolated sub-tree through forms, then zips
-   up to, and locates at, the root of the modified sub-tree."
+   up to, and locates at, the root of the modified sub-tree.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc & body] `(rewrite-clj.zip.subedit/subedit-> ~zloc ~@body))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.subedit
 (defmacro subedit->>
   "Like `->`. Threads `zloc`, as an isolated sub-tree through forms, then zips
-      up to, and locates at, the root of the modified sub-tree."
+      up to, and locates at, the root of the modified sub-tree.
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc & body] `(rewrite-clj.zip.subedit/subedit->> ~zloc ~@body))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.walk
@@ -753,7 +769,8 @@
        zip/up
        (zip/prewalk ...))
    ```
-   "
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   ([zloc f] (rewrite-clj.zip.walk/prewalk zloc f))
   ([zloc p? f] (rewrite-clj.zip.walk/prewalk zloc p? f)))
 
@@ -795,7 +812,8 @@
        zip/up
        (zip/postwalk ...))
    ```
-   "
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   ([zloc f] (rewrite-clj.zip.walk/postwalk zloc f))
   ([zloc p? f] (rewrite-clj.zip.walk/postwalk zloc p? f)))
 

src/rewrite_clj/zip/subedit.cljc

@@ -36,7 +36,9 @@
 (defn edit-node
   "Return zipper applying function `f` to `zloc`. The resulting
    zipper will be located at the same path (i.e. the same number of
-   downwards and right movements from the root) incoming `zloc`."
+   downwards and right movements from the root) incoming `zloc`.
+   
+   See also [[subedit-node]] for an isolated edit."
   [zloc f]
   (let [zloc' (f zloc)]
     (assert (not (nil? zloc')) "function applied in 'edit-node' returned nil.")
@@ -45,21 +47,27 @@
 (defmacro edit->
   "Like `->`, threads `zloc` through forms.
    The resulting zipper will be located at the same path (i.e. the same
-   number of downwards and right movements from the root) as incoming `zloc`."
+   number of downwards and right movements from the root) as incoming `zloc`.
+   
+   See also [[subedit->]] for an isolated edit."
   [zloc & body]
   `(edit-node ~zloc #(-> % ~@body)))
 
 (defmacro edit->>
   "Like `->>`, threads `zloc` through forms.
    The resulting zipper will be located at the same path (i.e. the same
-   number of downwards and right movements from the root) as incoming `zloc`."
+   number of downwards and right movements from the root) as incoming `zloc`.
+   
+   See also [[subedit->>]] for an isolated edit."
   [zloc & body]
   `(edit-node ~zloc #(->> % ~@body)))
 
 ;; ## Sub-Zipper
 
 (defn subzip
-  "Create and return a zipper whose root is the current node in `zloc`."
+  "Create and return a zipper whose root is the current node in `zloc`.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc]
   (let [zloc' (some-> zloc 
                       zraw/node 
@@ -69,20 +77,26 @@
 
 (defn subedit-node
   "Return zipper replacing current node in `zloc` with result of `f` applied to said node as an isolated sub-tree.
-   The resulting zipper will be located on the root of the modified sub-tree."
+   The resulting zipper will be located on the root of the modified sub-tree.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc f]
   (let [zloc' (f (subzip zloc))]
     (assert (not (nil? zloc')) "function applied in 'subedit-node' returned nil.")
     (zraw/replace zloc (zraw/root zloc'))))
 
 (defmacro subedit->
   "Like `->`, threads `zloc`, as an isolated sub-tree through forms, then zips
-   up to, and locates at, the root of the modified sub-tree."
+   up to, and locates at, the root of the modified sub-tree.
+   
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc & body]
   `(subedit-node ~zloc #(-> % ~@body)))
 
 (defmacro subedit->>
   "Like `->`. Threads `zloc`, as an isolated sub-tree through forms, then zips
-      up to, and locates at, the root of the modified sub-tree."
+      up to, and locates at, the root of the modified sub-tree.
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   [zloc & body]
   `(subedit-node ~zloc #(->> % ~@body)))

src/rewrite_clj/zip/walk.cljc

@@ -60,7 +60,8 @@
        zip/up
        (zip/prewalk ...))
    ```
-   "
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   ([zloc f] (prewalk zloc (constantly true) f))
   ([zloc p? f]
    (->> (partial prewalk-subtree p? f)
@@ -116,7 +117,8 @@
        zip/up
        (zip/postwalk ...))
    ```
-   "
+
+   See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing)."
   ([zloc f] (postwalk zloc (constantly true) f))
   ([zloc p? f]
    (subedit/subedit-node zloc #(postwalk-subtree p? f %))))

template/rewrite_clj/zip.cljc

@@ -121,17 +121,19 @@
   [[append-child*]]
   [[remove*]]
 
-  **Isolated update without changing location**
+  **Update without changing location**
   [[edit-node]]
+  [[edit->]]
+  [[edit->>]]
+
+  **Isolated update without changing location**
   [[subedit-node]]
   [[subzip]]
   [[prewalk]]
   [[postwalk]]
-  [[edit->]]
-  [[edit->>]]
   [[subedit->]]
   [[subedit->>]]
-
+ 
   **Sequence operations**
   [[map]]
   [[map-keys]]