illustrate.clj to Illustrate Clojure Snippet

This is what I came up at first:

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

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

(my-function 7)
")

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

(loop [cur zloc
       left cur]
  (println "current string {{" (z/string cur) "}}")
  (if (z/end? cur)
    (println "final string: {{" (z/root-string left) "}}") ; XXX it doesn't work as expected!!!
    (recur (z/right (z/insert-right cur (p/parse-string "; test\n")))
           cur)))

The output shows that it only works partially, the last comment didn't get appended:

current string {{ (defn my-function [a]
  (* a 3)) }}
current string {{ (my-function 7) }}
current string {{ nil }}
final string: {{ 
 (defn my-function [a]
  (* a 3)) ; test


(my-function 7)
 }}

It took me a lot of time to figure out why it doesn't work, but I failed to.

Then I turned to the #rewrite-clj community on Slack for help, @lread nicely gave me a workable solution:

(loop [zloc zloc]
  (let [zloc (some-> zloc
                     (z/insert-right* (n/comment-node "; test"))
                     (z/insert-right* (n/newlines 1)))
        next-sib (z/right zloc)]
    (if next-sib
      (recur next-sib)
      (z/print-root zloc))))

That was a good starting point for me. Looking back, the lessons here are:

1. The zipper or zloc of rewrite-clj is immutable, so be careful with the stale ones before modifications.

   The problem above was that the cur in the last recur sexpr is stale after applying z/insert-right, and the correct one would be like this:

   (loop [cur zloc
          left cur]
     (println "current string {{" (z/string cur) "}}")
     (if (z/end? cur)
       (println "final string: {{" (z/root-string left) "}}")
       (let [cur (z/insert-right cur (p/parse-string "; test\n"))] ; here is the diff
         (recur (z/right cur)
                cur))))

2. It's better to create nodes explicitly. At first, I thought (z/insert-right* (p/parse-string-all "\n; test\n")) would insert two nodes to the right, but it turned out it didn't work. Instead, inserting a comment and then a newline node did the trick, that is:

   (-> zloc
       (z/insert-right* (n/comment " test"))
       (z/insert-right* (n/newline 1)))

3. whitespace-node is different from newline-node for rewrite-clj, at the first glance, my intuition was that whitespace nodes also contains newlines.
4. Keep the number of loop bindings as little as possible, and only one is the best so that there is little for recur to care about.
5. The let bindings is an excellent place to put some logic so that the body of let would be concise.

After getting familiar with rewrite-clj, I get back to my track once again. The second version only contains 57 sloc, which is concise.

There are 3 ways to use it:

1. illustrate.clj -i .new foo.clj, to illustrate foo.clj and write the result to foo.new.clj.
2. illustrate.clj foo.clj, to illustrate foo.clj and overwrite it. Be careful! You'd better back up your file or put it under the control of git.
3. cat foo.clj | illustrate.clj to do it via a pipe. It could be handy if you use it with tools like Emacs/Vim.

There is still one feature that I leave for someday: to illustrate org-mode files containing Clojure source block, which would be wonderful for writing blog posts with Hugo.

Anyway, the script is on GitHub.