Added z/of-node, z/of-node*

lread · lread · commit 59f3c9ff42c0 · 2022-06-08T18:59:16.000-04:00
These are the same as the now deprecated rewrite-clj.zip/edn and rewrite-clj.zip/edn*. Name change is to reflect fn purpose and reduce user confusion. Closes #178
diff --git a/.clj-kondo/config.edn b/.clj-kondo/config.edn
@@ -54,4 +54,14 @@
              rewrite-clj.node.protocols/value
              {:namespaces [rewrite-clj.node rewrite-clj.zip.base]}
              rewrite-clj.node/value
-             {:defs [rewrite-clj.zip.base/value]}}}}}
+             {:defs [rewrite-clj.zip.base/value]}
+
+             rewrite-clj.zip/edn
+             {:namespaces [rewrite-clj.zip-test]}
+
+             rewrite-clj.zip/edn*
+             {:namespaces [;; this is a bb script usage which is using an older version rewrite-clj
+                           ;; can update code and remove when bb upgrades to rewrite-clj v1.1
+                           helper.deps-patcher
+                           ;; and this is legitimate, we still need to sanity test that the deprecated fn works
+                           rewrite-clj.zip-test]}}}}}
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -17,8 +17,13 @@ For a list of breaking changes see link:#v1-breaking[breaking changes].
 === Unreleased
 
 * dropped the alpha status
-* now properly escaping inline double quotes for coerced strings https://github.com/clj-commons/rewrite-clj/issues/176[#176] - thanks to @ivarref for raising the issue!
 * changed rewrite-clj library version scheme from commit-count to release-num https://github.com/clj-commons/rewrite-clj/issues/179[#179]
+* renamed zipper creation functions that take a rewrite-clj node as input.
+The old names did not reflect their purpose which led to confusion.
+Old functions will remain but are marked as deprecated. https://github.com/clj-commons/rewrite-clj/issues/178[#178]
+** `rewrite-clj.zip/edn` -> `rewrite-clj.zip/of-node`
+** `rewrite-clj.zip/edn*` -> `rewrite-clj.zip/of-node*`
+* now properly escaping inline double quotes for coerced strings https://github.com/clj-commons/rewrite-clj/issues/176[#176] - thanks to @ivarref for raising the issue!
 * docs:
 ** docstring fix, was missing `list-node` from toc, thanks @rfhayashi!
 
diff --git a/deps.edn b/deps.edn
@@ -29,8 +29,11 @@
                       :main-opts ["-m" "eastwood.lint" {:source-paths ["src"]
                                                         :test-paths ["test"]
                                                         :add-linters [:performance]
+                                                        ;; not too worried about eastwood finding deprecation usages,
+                                                        ;; we rely on clj-kondo for that
                                                         :ignored-faults {:deprecations {rewrite-clj.regression-test true
-                                                                                        rewrite-clj.zip.whitespace-test true}}}]}
+                                                                                        rewrite-clj.zip.whitespace-test true
+                                                                                        rewrite-clj.zip-test true}}}]}
 
            ;;
            ;; Test support
diff --git a/src/rewrite_clj/zip.cljc b/src/rewrite_clj/zip.cljc
@@ -205,24 +205,36 @@
   [zloc] (rewrite-clj.zip.base/child-sexprs zloc))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
-(defn edn*
-  "Create and return zipper from Clojure/ClojureScript/EDN `node` (likely parsed by [[rewrite-clj.parse]]).
+(defn ^{:added "1.1.45"} of-node*
+  "Create and return zipper from a rewrite-clj `node` (likely parsed by [[rewrite-clj.parse]]).
 
   Optional `opts` can specify:
   - `:track-position?` set to `true` to enable ones-based row/column tracking, see [docs on position tracking](/doc/01-user-guide.adoc#position-tracking).
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)"
+  ([node] (rewrite-clj.zip.base/of-node* node))
+  ([node opts] (rewrite-clj.zip.base/of-node* node opts)))
+
+;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
+(defn ^{:deprecated "1.1.45"} edn*
+  "DEPRECATED. Renamed to [[of-node*]]."
   ([node] (rewrite-clj.zip.base/edn* node))
   ([node opts] (rewrite-clj.zip.base/edn* node opts)))
 
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
-(defn edn
-  "Create and return zipper from Clojure/ClojureScript/EDN `node` (likely parsed by [[rewrite-clj.parse]]),
+(defn ^{:added "1.1.45"} of-node
+  "Create and return zipper from a rewrite-clj `node` (likely parsed by [[rewrite-clj.parser]]),
   and move to the first non-whitespace/non-comment child. If node is not forms node, is wrapped in forms node
   for a consistent root.
 
   Optional `opts` can specify:
   - `:track-position?` set to `true` to enable ones-based row/column tracking, see [docs on position tracking](/doc/01-user-guide.adoc#position-tracking).
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)"
+  ([node] (rewrite-clj.zip.base/of-node node))
+  ([node opts] (rewrite-clj.zip.base/of-node node opts)))
+
+;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
+(defn ^{:deprecated "1.1.45"} edn
+  "DEPRECATED. Renamed to [[of-node]]."
   ([node] (rewrite-clj.zip.base/edn node))
   ([node opts] (rewrite-clj.zip.base/edn node opts)))
 
diff --git a/src/rewrite_clj/zip/base.cljc b/src/rewrite_clj/zip/base.cljc
@@ -11,37 +11,50 @@
 
 ;; ## Zipper
 
-(defn edn*
-  "Create and return zipper from Clojure/ClojureScript/EDN `node` (likely parsed by [[rewrite-clj.parse]]).
+(defn of-node*
+  "Create and return zipper from a rewrite-clj `node` (likely parsed by [[rewrite-clj.parse]]).
 
   Optional `opts` can specify:
   - `:track-position?` set to `true` to enable ones-based row/column tracking, see [docs on position tracking](/doc/01-user-guide.adoc#position-tracking).
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)"
   ([node]
-   (edn* node {}))
+   (of-node* node {}))
   ([node opts]
    (-> (if (:track-position? opts)
          (zraw/custom-zipper node)
          (zraw/zipper node))
        (options/set-opts opts))))
 
-(defn edn
-  "Create and return zipper from Clojure/ClojureScript/EDN `node` (likely parsed by [[rewrite-clj.parse]]),
+(defn of-node
+  "Create and return zipper from a rewrite-clj `node` (likely parsed by [[rewrite-clj.parser]]),
   and move to the first non-whitespace/non-comment child. If node is not forms node, is wrapped in forms node
   for a consistent root.
 
   Optional `opts` can specify:
   - `:track-position?` set to `true` to enable ones-based row/column tracking, see [docs on position tracking](/doc/01-user-guide.adoc#position-tracking).
   - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)"
-  ([node] (edn node {}))
+  ([node] (of-node node {}))
   ([node opts]
    (loop [node node opts opts]
      (if (= (node/tag node) :forms)
-       (let [top (edn* node opts)]
+       (let [top (of-node* node opts)]
          (or (-> top zraw/down ws/skip-whitespace)
              top))
        (recur (nforms/forms-node [node]) opts)))))
 
+(defn edn*
+  "DEPRECATED. Renamed to [[of-node*]]."
+  ([node]
+   (edn* node {}))
+  ([node opts]
+   (of-node* node opts)))
+
+(defn edn
+  "DEPRECATED. Renamed to [[of-node]]."
+  ([node] (edn node {}))
+  ([node opts]
+   (of-node node opts)))
+
 ;; ## Inspection
 
 (defn tag
diff --git a/src/rewrite_clj/zip/subedit.cljc b/src/rewrite_clj/zip/subedit.cljc
@@ -31,7 +31,7 @@
   [zloc path]
   (let [root (-> zloc
                  zraw/root
-                 (base/edn* (options/get-opts zloc)))]
+                 (base/of-node* (options/get-opts zloc)))]
     (reduce move-step root path)))
 
 (defn edit-node
@@ -72,7 +72,7 @@
   [zloc]
   (let [zloc' (some-> zloc
                       zraw/node
-                      (base/edn* (options/get-opts zloc)))]
+                      (base/of-node* (options/get-opts zloc)))]
     (assert zloc' "could not create subzipper.")
     zloc'))
 
diff --git a/template/rewrite_clj/zip.cljc b/template/rewrite_clj/zip.cljc
@@ -176,7 +176,10 @@
 
            [rewrite-clj.zip.base
             ^{:added "0.4.4"} child-sexprs
-            edn* edn
+            ^{:added "1.1.45"} of-node*
+            ^{:deprecated "1.1.45"} edn*
+            ^{:added "1.1.45"} of-node
+            ^{:deprecated "1.1.45"} edn
             tag sexpr sexpr-able?
             length
             ^{:deprecated "0.4.0"} value
diff --git a/test/rewrite_clj/custom_zipper/core_test.cljc b/test/rewrite_clj/custom_zipper/core_test.cljc
@@ -163,7 +163,7 @@
   (prop/for-all [node (g/node)
                  operations (gen/vector (gen/elements (keys operations)) 1 8)]
                 (let [zloc (apply-operations
-                            (base/edn* node {:track-position? true})
+                            (base/of-node* node {:track-position? true})
                             operations)]
                   (= (char-here zloc)
                      (char-at-position (base/root-string zloc) (z/position zloc))))))
diff --git a/test/rewrite_clj/custom_zipper/utils_test.cljc b/test/rewrite_clj/custom_zipper/utils_test.cljc
@@ -11,7 +11,7 @@
         b (node/token-node 'b)
         c (node/token-node 'c)
         d (node/token-node 'd)
-        loc (z/down (base/edn* (node/forms-node [a b c d])))]
+        loc (z/down (base/of-node* (node/forms-node [a b c d])))]
     (testing "remove-right"
       (let [loc' (u/remove-right loc)]
         (is (= 'a (base/sexpr loc')))
diff --git a/test/rewrite_clj/zip/base_test.cljc b/test/rewrite_clj/zip/base_test.cljc
@@ -8,7 +8,7 @@
            [(node/spaces 3)
             (node/coerce [[1 2] 3])])
         s "   [[1 2] 3]"
-        loc (z/edn* n)
+        loc (z/of-node* n)
         [_ a b c d] (iterate z/next* loc)]
       (is (= :forms (z/tag loc)))
       (is (= [[1 2] 3] (z/sexpr loc)))
@@ -49,7 +49,7 @@
                      (with-open [w (java.io.StringWriter.)]
                        (z/print-root loc w)
                        (str w)))))
-         (z/edn
+         (z/of-node
           (node/forms-node
            [(node/spaces 3)
             (node/coerce [[1 2] 3])]))
@@ -60,7 +60,7 @@
 (deftest t-zipper-creation-for-whitespace-only-nodes
   (are [?ws ?s]
        (let [n (node/forms-node [?ws])
-             loc (z/edn n)]
+             loc (z/of-node n)]
          (is (= :forms (z/tag loc)))
          (is (= nil (z/sexpr loc)))
          (is (= ?s (z/string loc)))
diff --git a/test/rewrite_clj/zip/whitespace_test.cljc b/test/rewrite_clj/zip/whitespace_test.cljc
@@ -9,7 +9,7 @@
         c0 (node/comment-node "comment")
         t0 (node/token-node 0)
         t1 (node/token-node 1)
-        loc (z/edn* (node/forms-node [space linebreak t0 space t1 c0]))]
+        loc (z/of-node* (node/forms-node [space linebreak t0 space t1 c0]))]
     (testing "predicates"
       (is (z/whitespace? (-> loc z/down*)))
       (is (z/linebreak? (-> loc z/down* z/right*)))
diff --git a/test/rewrite_clj/zip_test.cljc b/test/rewrite_clj/zip_test.cljc
@@ -251,3 +251,29 @@
                    z/down* z/rightmost* z/left* z/left* z/remove* z/up*
                    z/sexpr))
             (msg "raw ops sanity test"))))))
+
+(deftest t-from-nodes
+  (let [my-node (n/keyword-node :hey)]
+    ;; z/edn is deprecated but it remains and should work
+    (doseq [nf [z/of-node z/edn]]
+      (is (= ":hey" (-> (n/forms-node [(n/spaces 3) my-node])
+                        nf
+                        z/string)))
+      (is (= [1 4] (-> (n/forms-node [(n/spaces 3) my-node])
+                       (nf {:track-position? true})
+                       (z/position))))
+      (is (= :forms (-> my-node
+                        nf
+                        z/up
+                        z/tag))))
+    ;; z/edn* is deprecated but it remains and should work
+    (doseq [nf [z/of-node* z/edn*]]
+      (is (= "   :hey" (-> (n/forms-node [(n/spaces 3) my-node])
+                        nf
+                        z/string)))
+      (is (= [1 1] (-> (n/forms-node [(n/spaces 3) my-node])
+                       (nf {:track-position? true})
+                       (z/position))))
+      (is (= :token (-> my-node
+                        nf
+                        z/tag))))))
