update README.md

Author: Yannick Scherer

README.md

@@ -18,39 +18,60 @@ __Leiningen ([via Clojars](http://clojars.org/rewrite-clj))__
 
 [![Clojars Project](http://clojars.org/rewrite-clj/latest-version.svg)](http://clojars.org/rewrite-clj)
 
+Auto-generated documentation can be found [here](http://xsc.github.io/rewrite-clj/).
+
 ### Parsing Data
 
-The parser relies on [clojure.tools.reader](https://github.com/clojure/tools.reader) when handling simple
-tokens. It generates a structure of nested vectors whose first elements represent the kind of data
-contained (`:token`, `:whitespace`, `:comment`, `:list`, ...).
+The parser relies on [clojure.tools.reader](https://github.com/clojure/tools.reader) when
+handling simple tokens and generates a custom node type representing EDN forms:
 
 ```clojure
 (require '[rewrite-clj.parser :as p])
-(p/parse-string "(defn my-function [a]\n  (* a 3))")
-;; =>
-;; [:list
-;;   [:token defn] [:whitespace " "] [:token my-function] [:whitespace " "]
-;;   [:vector [:token a]] [:newline "\n"] [:whitespace "  "]
-;;   [:list
-;;     [:token *] [:whitespace " "] [:token a] [:whitespace " "] [:token 3]]]
+
+(p/parse-string "(defn my-function [a]\n  (* a 3))"
+;; => <list:
+;;      (defn my-function [a]
+;;        (* a 3))
+;;    >
 ```
 
-### Printing Data
+These nodes can be analysed using functions in `rewrite-clj.node`:
+
+```clojure
+(require '[rewrite-clj.node :as n])
+
+(n/tag form)          ;; => :list
+(n/children form)     ;; => (<token: defn> <whitespace: " "> <token: my-function> ...)
+(n/sexpr form)        ;; => (defn my-function [a] (* a 3))
+(n/child-sexprs form) ;; => (defn my-function [a] (* a 3))
+```
 
-The printer incorporates whitespaces and comments in its output.
+To convert the structure back to a printable string, use:
 
 ```clojure
-(require '[rewrite-clj.printer :as prn])
-(prn/print-edn (p/parse-string "(defn my-function [a]\n  (* a 3))"))
-;; (defn my-function [a]
-;;   (* a 3))
-;; => nil
+(n/string form) ;; => "(defn my-function [a]\n  (* a 3))"
+```
+
+You can create a node from nearly any value using `coerce`:
+
+```
+(n/coerce '[a b c]) ;; => <vector: [a b c]>
+```
+
+Alternatively, by hand:
+
+```
+(n/meta-node
+  (n/token-node :private)
+  (n/token-node 'sym))
+;; => <meta: ^:private sym>
 ```
 
 ### Clojure Zipper
 
-To traverse/modify the generated structure you can use rewrite-clj's whitespace-/comment-/value-aware zipper
-operations, based on [fast-zip](https://github.com/akhudek/fast-zip).
+To traverse/modify the generated structure you can use rewrite-clj's
+whitespace-/comment-/value-aware zipper operations, based on
+[fast-zip](https://github.com/akhudek/fast-zip).
 
 ```clojure
 (require '[rewrite-clj.zip :as z])
@@ -61,7 +82,7 @@ operations, based on [fast-zip](https://github.com/akhudek/fast-zip).
 (def data (z/of-string data-string))
 
 (z/sexpr data)                       ;; => (defn my-function [a] (* a 3))
-(-> data z/down z/right z/node)      ;; => [:token my-function]
+(-> data z/down z/right z/node)      ;; => <token: my-function>
 (-> data z/down z/right z/sexpr)     ;; => my-function
 
 (-> data z/down z/right (z/edit (comp symbol str) "2") z/up z/sexpr)
@@ -74,26 +95,28 @@ operations, based on [fast-zip](https://github.com/akhudek/fast-zip).
 ;; => nil
 ```
 
-`rewrite-clj.zip/edit` and `rewrite-clj.zip/replace` try to facilitate their use by transparently converting
-between the node's internal representation (`[:token my-function]`) and its corresponding s-expression (`my-function`).
+`rewrite-clj.zip/edit` and `rewrite-clj.zip/replace` try to facilitate their use
+by transparently coercing between the node's internal representation (`<token: my-function>`)
+and its corresponding s-expression (`my-function`).
 
 ## Sweet Code Traversal
 
 ### Example
 
-`rewrite-clj.zip` offers a series of `find` operations that can be used to determine specific positions in the code.
-For example, you might want to modify a `project.clj` of the following form by replacing the `:description` placeholder
-text with something meaningful:
+`rewrite-clj.zip` offers a series of `find` operations that can be used to determine specific
+positions in the code. For example, you might want to modify a `project.clj` of the following
+form by replacing the `:description` placeholder text with something meaningful:
 
 ```clojure
 (defproject my-project "0.1.0-SNAPSHOT"
   :description "Enter description"
   ...)
 ```
 
-Most find operations take an optional movement function as parameter. If you wanted to perform a depth-first search you'd
-use `rewrite-clj.zip/next`, if you wanted to look for something on the same level as the current location, you'd employ
-`rewrite-clj.zip/right` (the default) or `rewrite-clj.zip/left`.
+Most find operations take an optional movement function as parameter. If you wanted to perform
+a depth-first search you'd use `rewrite-clj.zip/next`, if you wanted to look for something on
+the same level as the current location, you'd employ `rewrite-clj.zip/right` (the default) or
+`rewrite-clj.zip/left`.
 
 Now, to enter the project map, you'd look for the symbol `defproject` in a depth-first way:
 
@@ -119,25 +142,13 @@ Replace it, zip up and print the result:
 ;; => nil
 ```
 
-### Searching the Tree
-
-Search functions include:
-
-- `(find zloc [f] p?)`: find the first match for the given predicate by repeatedly applying `f` to the current zipper
-  location (default movement: `rewrite-clj.zip/right`). This might return `zloc` itself.
-- `(find-next zloc [f] p?)`: find the next match for the given predicate by repeatedly applying `f` to the current zipper
-  location (default movement: `rewrite-clj.zip/right`). This will not return `zloc` itself.
-- `(find-tag zloc [f] t)`: uses `find` to get the first node with the given tag.
-- `(find-next-tag zloc [f] t)`: uses `find-next` to get the first node with the given tag.
-- `(find-token zloc [f] p?)`: like `find` but will only check `:token` nodes. The predicate is applied to the node's value.
-- `(find-next-token zloc [f] p?)`: like `find-next` but will only check `:token` nodes.
-- `(find-value zloc [f] v)`: uses `find` to get the first `:token` node with the given value.
-- `(find-next-value zloc [f] v)`: uses `find-next` to get the first `:token` node with the given value.
+See the [auto-generated documentation](http://xsc.github.io/rewrite-clj/) for more information.
 
 ### Handling Clojure Data Structures
 
-rewrite-clj aims at providing easy ways to work with Clojure data structures. It offers functions corresponding
-to the standard seq functions designed to work with zipper nodes containing said structures, e.g.:
+rewrite-clj aims at providing easy ways to work with Clojure data structures. It offers
+functions corresponding to the standard seq functions designed to work with zipper nodes
+containing said structures, e.g.:
 
 ```clojure
 (def data (z/of-string "[1\n2\n3]"))
@@ -151,16 +162,7 @@ to the standard seq functions designed to work with zipper nodes containing said
 ;; => "[5\n6\n7]"
 ```
 
-The following functions exist:
-
-- `map`: takes a function to be applied to the zipper nodes of the seq's values, has to return the
-  modified zipper node. If a `:map` node is supplied, the value nodes will be iterated over. Returns
-  the supplied node incorporating all changes.
-- `map-keys`: Iterate over the key nodes of a `:map` node.
-- `get`: can be applied to `:map` nodes (with a key) or `:vector`/`:list`/`:set` nodes (with a numerical index)
-  and will return the desired zipper location.
-- `assoc`: will replace the value at the location obtained via `get`.
-- `seq?`, `map?`, `vector?`, `list?`, `set?`: check the type of the given zipper node.
+See the [auto-generated documentation](http://xsc.github.io/rewrite-clj/) for more information.
 
 ## License