Add sexpr-able? to node and zip APIs

Closes #113

Author: lread

CHANGELOG.adoc

@@ -42,14 +42,17 @@ Rewrite-cljs users migrating to rewrite-clj v1 are now at, and will remain at, f
 *** Adds namespaced element support functions
 **** `reapply-context` - reapplies (or removes) map qualifier node context from keywords and symbols
 **** zipper creation functions now optionally accept an auto-resolve function to support sexpr on namespaced element nodes
+*** Other additions
+**** `sexpr-able?` - return true if `sexpr` is supported for current node
 ** `rewrite-clj.node`
 *** Additions:
 **** `keyword-node?` - returns true if form is a rewrite-clj keyword node
 **** `map-qualifier-node` - to create a namespaced map's map qualifier node manually
 **** `map-context-apply` - apply map qualifier to keyword or symbol
 **** `map-context-clear` - remove map qualifier from keyword or symbol
 **** `node?` - returns true if a form is a rewrite-clj created node
-**** `symbol-node?` - return true if node is a rwrite-clj symbol node
+**** `sexpr-able?` - return true if `sexpr` is supported for node
+**** `symbol-node?` - return true if node is a rewrite-clj symbol node
 *** Updates:
 **** `sexpr`, `sepxrs` and `child-sexprs` - now optionally take an options argument to specify an auto-resolve function
 * Many updates to docs and docstrings

doc/01-user-guide.adoc

@@ -575,29 +575,67 @@ The whitespace that a rewrite-clj so carefully preserves is lost when converting
 
 === Not all Source is Sexpr-able
 
-Some source code elements are not sexpr-able.
-Reader ignore/discard `#_`, comment and whitespace all throw an "unsupported operation" exception.
+Some source code elements are not sexpr-able:
+
+* Reader ignore/discard `#_` (also known as "uneval" in rewrite-clj)
+* Comments
+* Clojure whitespace (which includes commas)
+
+Both the zip and node APIs include `sexpr-able?` to check if sexpr is supported for a node.
 
 [source, clojure]
 ----
-(require '[rewrite-clj.zip :as z])
+(require '[rewrite-clj.node :as n]
+         '[rewrite-clj.parser :as p]
+         '[rewrite-clj.zip :as z])
 
 #?(:clj (import clojure.lang.ExceptionInfo))
 
+;;
+;; Most nodes are sexpr-able
+;;
+
+;; we can check sexpr-ability through the node API
+(-> "hello" p/parse-string n/sexpr-able?)
+;; => true
+
+;; or through the zip API
+(-> "hello" z/of-string z/sexpr-able?)
+;; => true
+
+;;
+;; But some nodes are not sexpr-able
+;;
+
+;; the discard #_ node is not sexpr-able
+(-> "#_42" z/of-string z/sexpr-able?)
+;; => false
+
+;; and will throw if an attempt is made to sexpr
 (try
-  (-> (z/of-string "#_42") z/sexpr)
+  (-> "#_42" z/of-string z/sexpr)
   (catch ExceptionInfo e
     (ex-message e)))
 ;; => "unsupported operation"
 
+;; comments nodes are not sexpr-able
+(-> ";; can’t sexpr me!" z/of-string z/next* z/sexpr-able?) ;; <1>
+;; => false
+
+;; and will throw
 (try
-  (-> (z/of-string ";; can’t sexpr me!") z/next* z/sexpr) ;; <1>
+  (-> ";; can’t sexpr me!" z/of-string z/next* z/sexpr) ;; <1>
   (catch ExceptionInfo e
     (ex-message e)))
 ;; => "unsupported operation"
 
+;; and finally, Clojure whitespace nodes are not sexpr-able
+(-> " " z/of-string z/next* z/sexpr-able?) ;; <1>
+;; => false
+
+;; and will throw
 (try
-  (-> (z/of-string " ") z/next* z/sexpr) ;; <1>
+  (-> " " z/of-string z/next* z/sexpr) ;; <1>
   (catch ExceptionInfo e
     (ex-message e)))
 ;; => "unsupported operation"

src/rewrite_clj/node.cljc

@@ -87,6 +87,11 @@
   ([node] (rewrite-clj.node.protocols/sexpr node))
   ([node opts] (rewrite-clj.node.protocols/sexpr node opts)))
 
+;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.node.protocols
+(defn sexpr-able?
+  "Return true if [[sexpr]] is supported for `node`."
+  [node] (rewrite-clj.node.protocols/sexpr-able? node))
+
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.node.protocols
 (defn sexprs
   "Return forms for `nodes`. Nodes that do not represent s-expression are skipped.

src/rewrite_clj/node/namespaced_map.cljc

@@ -7,7 +7,7 @@
   node/Node
   (tag [_node] :map-qualifier)
   (node-type [_node] :map-qualifier)
-  (printable-only? [_node] true)
+  (printable-only? [_node] false)
   (sexpr* [_node opts]
     (if auto-resolved?
       ((or (:auto-resolve opts) node/default-auto-resolve)

src/rewrite_clj/node/protocols.cljc

@@ -31,6 +31,11 @@
   (length [this] (count (string this)))
   (string [this] (pr-str this)))
 
+(defn sexpr-able?
+  "Return true if [[sexpr]] is supported for `node`."
+  [node]
+  (not (printable-only? node)))
+
 (defn sexpr
   "Return `node` converted to form.
 

src/rewrite_clj/zip.cljc

@@ -90,6 +90,7 @@
   [[length]]
 
   **Convert**
+  [[sexpr-able?]]
   [[sexpr]]
   [[child-sexprs]]
   [[reapply-context]]
@@ -233,6 +234,11 @@
   See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances)."
   [zloc] (rewrite-clj.zip.base/sexpr zloc))
 
+;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
+(defn sexpr-able?
+  "Return true if current node in `zloc` can be [[sexpr]]-ed."
+  [zloc] (rewrite-clj.zip.base/sexpr-able? zloc))
+
 ;; DO NOT EDIT FILE, automatically imported from: rewrite-clj.zip.base
 (defn length
   "Return length of printable string of current node in `zloc`."

src/rewrite_clj/zip/base.cljc

@@ -57,6 +57,11 @@
   [zloc]
   (some-> zloc zraw/node node/tag))
 
+(defn sexpr-able?
+  "Return true if current node in `zloc` can be [[sexpr]]-ed."
+  [zloc]
+  (some-> zloc zraw/node node/sexpr-able?))
+
 (defn sexpr
   "Return s-expression (the Clojure form) of current node in `zloc`.
 

template/rewrite_clj/node.cljc

@@ -39,6 +39,7 @@
             printable-only?
             replace-children
             sexpr
+            sexpr-able?
             sexprs
             map-context-apply
             map-context-clear

template/rewrite_clj/zip.cljc

@@ -89,6 +89,7 @@
   [[length]]
 
   **Convert**
+  [[sexpr-able?]]
   [[sexpr]]
   [[child-sexprs]]
   [[reapply-context]]
@@ -172,7 +173,7 @@
            [rewrite-clj.zip.base
             child-sexprs
             edn* edn
-            tag sexpr
+            tag sexpr sexpr-able?
             length
             value
             of-string

test/rewrite_clj/node_test.cljc

@@ -5,41 +5,53 @@
             [rewrite-clj.node.protocols :as proto]
             [rewrite-clj.parser :as p]))
 
-(deftest nodes-convert-to-strings
+(deftest nodes-convert-to-strings-and-sexpr-ability
   (testing "easily parseable"
-    (are [?in ?expected-tag ?expected-type]
-        (let [n (p/parse-string ?in)]
+    (are [?in ?expected-tag ?expected-type ?expected-sexpr-able?]
+      (let [n (p/parse-string ?in)]
           (is (= ?in (str n)))
           (is (= ?expected-tag (n/tag n)))
-          (is (= ?expected-type (proto/node-type n))))
-      ","               :comma          :comma
-      "; comment"       :comment        :comment
-      "@deref"          :deref          :deref
-      "#(fn %1)"        :fn             :fn
-      ;; forms
-      ;; int
-      ":my-kw"          :token          :keyword
-      "^:meta b"        :meta           :meta
-      "#:prefix {:a 1}" :namespaced-map :namespaced-map
-      "\n"              :newline        :newline
-      "'quoted"         :quote          :quote
-      "#booya 32"       :reader-macro   :reader-macro
-      "#'myvar"         :var            :reader
-      "#\"regex\""      :regex          :regex
-      "[1 2 3]"         :vector         :seq
-      "\"string\""      :token          :string
-      "symbol"          :token          :symbol
-      "43"              :token          :token
-      "#_ nope"         :uneval         :uneval
-      "  "              :whitespace     :whitespace))
+          (is (= ?expected-type (proto/node-type n)))
+          (is (= ?expected-sexpr-able? (n/sexpr-able? n))))
+      ","               :comma          :comma              false
+      "; comment"       :comment        :comment            false
+      "@deref"          :deref          :deref              true
+      "#(fn %1)"        :fn             :fn                 true
+      ":my-kw"          :token          :keyword            true
+      "^:meta b"        :meta           :meta               true
+      "#:prefix {:a 1}" :namespaced-map :namespaced-map     true
+      "\n"              :newline        :newline            false
+      "'quoted"         :quote          :quote              true
+      "#booya 32"       :reader-macro   :reader-macro       true
+      "#'myvar"         :var            :reader             true
+      "#\"regex\""      :regex          :regex              true
+      "[1 2 3]"         :vector         :seq                true
+      "\"string\""      :token          :string             true
+      "symbol"          :token          :symbol             true
+      "43"              :token          :token              true
+      "#_ nope"         :uneval         :uneval             false
+      "  "              :whitespace     :whitespace         false))
   (testing "map qualifier"
-    (is (= ":prefix" (str (n/map-qualifier-node false "prefix"))))
-    (is (= "::" (str (n/map-qualifier-node true nil))))
-    (is (= "::nsalias" (str (n/map-qualifier-node true "nsalias")))))
+    (are [?auto-resolved ?prefix ?expected-str]
+      (let [n (n/map-qualifier-node ?auto-resolved ?prefix)]
+        (is (= ?expected-str (str n)))
+        (is (= :map-qualifier (n/tag n)))
+        (is (= :map-qualifier (proto/node-type n)))
+        (is (= true (n/sexpr-able? n))))
+      false "prefix"  ":prefix"
+      true  nil       "::"
+      true  "nsalias" "::nsalias"))
   (testing "integer"
-    (is (= "42" (str (n/integer-node 42)))))
+    (let [n (n/integer-node 42)]
+      (is (= :token (n/tag n)))
+      (is (= :int (proto/node-type n)))
+      (is (= "42" (str n)))
+      (is (n/sexpr-able? n))))
   (testing "forms node"
-    (is (= "5 7" (str (p/parse-string-all "5 7"))))))
+    (let [n (p/parse-string-all "5 7")]
+      (is (= "5 7" (str n)))
+      (is (n/sexpr-able? n)))))
+
 
 (deftest namespaced-keyword
   (is (= ":dill/dall"