User Guide

(require '[rewrite-clj.zip :as z])

;; define some test data
(def data-string
"(defn my-function [a]
  ;; a comment
  (* a 3))")

;; parse code to nodes, create a zipper, and navigate to the first non-whitespace node
(def zloc (z/of-string data-string))

;; explore what we've parsed
(z/sexpr zloc)
;; => (defn my-function [a] (* a 3))
(-> zloc z/down z/right z/node pr)
;; =stdout=>
; <token: my-function>
(-> zloc z/down z/right z/sexpr)
;; => my-function

;; rename my-function to my-function2 and return resulting s-expression
(-> zloc
    z/down
    z/right
    (z/edit (comp symbol str) "2")
    z/up
    z/sexpr)
;; => (defn my-function2 [a] (* a 3))

;; rename my-function to my-function2 and return updated string from root node
(-> zloc
    z/down
    z/right
    (z/edit (comp symbol str) "2")
    z/root-string
    println)
;; =stdout=>
; (defn my-function2 [a]
;   ;; a comment
;   (* a 3))

(defproject my-project "0.1.0-SNAPSHOT"
  :description "Enter description")

(require '[rewrite-clj.zip :as z])

;; for sake of a runnable example we'll load from a string:
(def zloc (z/of-string
"(defproject my-project \"0.1.0-SNAPSHOT\"
  :description \"Enter description\")"))

;; loading from a file, looks like so:
;; (def zloc (z/of-file "project.clj")) (1)

;; find defproject by navigating depth-first
(def zloc-defproject (z/find-value zloc z/next 'defproject))
;; verify that we are where we think we are
(z/sexpr zloc-defproject)
;; => defproject

;; search right for :description and then move one node to the right (2)
(def zloc-desc (-> zloc-defproject (z/find-value :description) z/right))
;; check that this worked
(z/sexpr zloc-desc)
;; => "Enter description"

;; replace node at current location and return the result
(-> zloc-desc (z/replace "My first Project.") z/root-string println)
;; =stdout=>
; (defproject my-project "0.1.0-SNAPSHOT"
;   :description "My first Project.")

(require '[rewrite-clj.zip :as z])

(def zloc (z/of-string "[1\n2\n3]"))
(z/vector? zloc)
;; => true
(z/sexpr zloc)
;; => [1 2 3]
(-> zloc (z/get 1) z/node pr)
;; =stdout=>
; <token: 2>
(-> zloc (z/assoc 1 5) z/sexpr)
;; => [1 5 3]
(->> zloc (z/map #(z/edit % + 4)) z/root-string)
;; => "[5\n6\n7]"

(def zloc (z/of-string "{:a 10 :b 20}"))
(z/map? zloc)
;; => true
(-> zloc (z/get :b) z/node pr)
;; =stdout=>
; <token: 20>
(-> zloc (z/assoc :b 42) z/sexpr)
;; => {:b 42, :a 10}
(->> zloc (z/map-vals #(z/edit % inc)) z/root-string)
;; => "{:a 11 :b 21}"
(->> zloc
     (z/map-keys #(z/edit %
                          (fn [v] (keyword "prefix" (name v))) ))
     z/root-string)
;; => "{:prefix/a 10 :prefix/b 20}"

(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"

(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]]])"

(require '[rewrite-clj.zip :as z])

;; parse some Clojure into a position tracking zipper
(def zloc (z/of-string
           "(defn sum-me\n  \"Add 'em up!\"\n  [a b c]\n  (+ a\n     c))"
           {:track-position? true}))

;; let's see what that looks like printed out
(println (z/root-string zloc))
;; =stdout=>
; (defn sum-me
;   "Add 'em up!"
;   [a b c]
;   (+ a
;      c))

;; navigate to second z in zipper
(def zloc-c (-> zloc
            (z/find-value z/next '+)
            (z/find-value z/next 'c)))

;; check if current node is as expected
(z/string zloc-c)
;; => "c"

;; examine position of second z, it is on 6th column of the 5th row
(z/position zloc-c)
;; => [5 6]

;; insert new element b with indentation and alignment
(def zloc-c2 (-> zloc-c
                 (z/insert-left 'b)        ;; insert b to the left of c
                 (z/left)                  ;; move to b
                 (z/insert-newline-right)  ;; insert a newline after b
                 (z/right)                 ;; move to c
                 (z/insert-space-left 4))) ;; c has 1 space before it, add 4 more to line it up

;; we should still be at c
(z/string zloc-c2)
"c"

;; output our updated Clojure
(println (z/root-string zloc-c2))
;; =stdout=>
; (defn sum-me
;   "Add 'em up!"
;   [a b c]
;   (+ a
;      b
;      c))

;; and check that location of c has been updated, it should now be on the 6th column of the 6th row
(z/position zloc-c2)
;; => [6 6]

(require '[rewrite-clj.zip :as z])

;; some contrived options to demonstrate:
(def zip-opts {:track-position true
               :auto-resolve (fn [_alias] 'custom-resolved)})


(-> "(+ 10 20 30)"         ;; <- something more complicated would be here, of course
    (z/of-string zip-opts) ;; <- our opts are passed in on creation
    z/down z/right z/right
    (z/edit inc)
    z/root                 ;; <- applying changes and getting root node
    (z/edn zip-opts)       ;; <- pass the original zip-opts on creation of new zipper
    z/down z/right z/right
    (z/edit inc)
    (z/root-string))
;; => "(+ 10 22 30)"

(-> (n/coerce '#(+ %1 %2))
    n/string)
;; => "(fn* [p1__10532# p2__10533#] (+ p1__10532# p2__10533#))"

(-> (n/vector-node [1 (n/spaces 1) 2 (n/spaces 1) 3])
    n/string)
;; => "[1 2 3]"

(n/tag 1)
;; :unknown

(require '[rewrite-clj.parser :as p]
         '[rewrite-clj.node :as n])

(-> (p/parse-string "::kw") n/sexpr)
;; => :?_current-ns_?/kw
(-> (p/parse-string "#::{:a 1 :b 2 s1 3}") n/sexpr)
;; => #:?_current-ns_?{s1 3, :b 2, :a 1}
(-> (p/parse-string "::my-alias/kw") n/sexpr)
;; => :??_my-alias_??/kw
(-> (p/parse-string "#::my-alias{:a 1 :b 2 s1 3}") n/sexpr)
;; => #:??_my-alias_??{s1 3, :b 2, :a 1}

(require '[rewrite-clj.parser :as p]
         '[rewrite-clj.node :as n])

(defn resolver [alias]
  (or (get {:current 'my.current.ns
            'my-alias 'my.aliased.ns} alias)
      (symbol (str alias "-unresolved"))))

(-> (p/parse-string "::kw") (n/sexpr {:auto-resolve resolver}))
;; => :my.current.ns/kw
(-> (p/parse-string "#::{:a 1 :b 2 s1 3}") (n/sexpr {:auto-resolve resolver}))
;; => #:my.current.ns{s1 3, :b 2, :a 1}
(-> (p/parse-string "::my-alias/kw") (n/sexpr {:auto-resolve resolver}))
;; => :my.aliased.ns/kw
(-> (p/parse-string "#::my-alias{:a 1 :b 2 s1 3}") (n/sexpr {:auto-resolve resolver}))
;; => #:my.aliased.ns{s1 3, :b 2, :a 1}

(require '[rewrite-clj.zip :as z])

;; get on unqualified keys is straightforward:
(-> "{:a 1 :b 2 c 3}" z/of-string (z/get :b) z/node pr)
;; =stdout=>
; <token: 2>

;; get on qualified keys is also easy to grok
(-> "{:a 1 :prefix/b 2 c 3}" z/of-string (z/get :prefix/b) z/node pr)
;; =stdout=>
; <token: 2>
(-> "#:prefix{:a 1 :b 2 c 3}" z/of-string (z/get :prefix/b) z/node pr)
;; =stdout=>
; <token: 2>
(-> "#:prefix{:a 1 :b 2 c 3}" z/of-string (z/get 'prefix/c) z/node pr)
;; =stdout=>
; <token: 3>

;; but when we introduce auto-resolved elements, the default resolver comes into play
;; and must be considered
(-> "{::ns-alias/a 1 ::b 2 c 3}" z/of-string (z/get :?_current-ns_?/b) z/node pr)
;; =stdout=>
; <token: 2>
(-> "{::ns-alias/a 1 ::b 2 c 3}" z/of-string (z/get :??_ns-alias_??/a) z/node pr)
;; =stdout=>
; <token: 1>
(-> "#::{:a 1 :b 2 c 3}" z/of-string (z/get :?_current-ns_?/b) z/node pr)
;; =stdout=>
; <token: 2>
(-> "#::{:a 1 :b 2 c 3}" z/of-string (z/get '?_current-ns_?/c) z/node pr)
;; =stdout=>
; <token: 3>

(require '[rewrite-clj.zip :as z])

(def zloc (z/of-string "#:my-prefix {:a 1 :b 2 c 3}"))

;; An sexpr on the namespaced map returns the expected Clojure form
( -> zloc z/sexpr)
;; => #:my-prefix{:b 2, c 3, :a 1}

;; An sepxr on the an individual key in the namespaced map returns the expected Clojure form
(-> zloc z/down z/rightmost z/down z/sexpr)
;; => :my-prefix/a

(require '[rewrite-clj.zip :as z])

(def s "#:prefix {:a 1 :b 2 c 3}")

;; sexpr works fine on unchanged zipper
(-> s z/of-string z/sexpr)
;; => #:prefix{:b 2, c 3, :a 1}

;; changing the namespaced map prefix reapplies the context to the children
(-> s
    z/of-string
    z/down
    (z/replace (n/map-qualifier-node false "my-new-prefix"))
    z/up
    z/sexpr)
;; => #:my-new-prefix{:b 2, c 3, :a 1}

;; a new key/val gets the namespaced map context
(-> s
    z/of-string
    z/down z/rightmost
    (z/append-child :d)
    (z/append-child 33)
    z/up
    z/sexpr)
;; => #:prefix{:b 2, c 3, :d 33, :a 1}

;; a replaced key gets namespaced map context
(-> s
    z/of-string
    z/down z/rightmost z/down
    (z/replace :a2)
    z/up z/up
    z/sexpr)
;; => #:prefix{:a2 1, :b 2, c 3}

;; but... be aware that the context is not applied...
(-> s
    z/of-string
    z/down z/rightmost z/down
    (z/replace :a2)
    z/sexpr)
;; => :a2

;; ... until we move up to the namespaced map node:
(-> s
    z/of-string
    z/down z/rightmost z/down
    (z/replace :a2)
    z/up z/up
    z/down z/rightmost z/down
    z/sexpr)
;; => :prefix/a2