rewrite-clj.node — rewrite-clj 1.2.51

Create, update, convert and integorate nodes.

All nodes represent Clojure/ClojureScript/EDN.

Because this API contains many functions, we offer the following categorized listing:

Node creation comma-node comment-node deref-node eval-node fn-node forms-node integer-node keyword-node list-node map-node map-qualifier-node meta-node namespaced-map-node newline-node quote-node raw-meta-node reader-macro-node regex-node set-node string-node syntax-quote-node token-node uneval-node unquote-node unquote-splicing-node var-node vector-node whitespace-node

Whitespace creation convenience spaces newlines comma-separated line-separated whitespace-nodes

Convert form to node coerce

Convert node to form sexpr-able? sexpr sexprs child-sexprs

Convert node to string string

Node interogation tag inner? children length leader-length printable-only?

Update node replace-children

Namespaced map element support map-context-apply map-context-clear

Test type node? comment? whitespace-or-comment? keyword-node? symbol-node? linebreak? comma?

child-sexprs clj/s

(child-sexprs node)

(child-sexprs node opts)

Returns children for node converted to Clojure forms.

Optional opts can specify:

• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

children clj/s

(children node)

Returns child nodes for node.

coerce clj/s

(coerce form)

Coerce form to node.

comma-node clj/s

(comma-node s)

Create comma node of string s, where s is one or more comma characters.

comma-separated clj/s

(comma-separated nodes)

Interleave nodes with ", " nodes.

comma? clj/s

(comma? node)

Returns true if node represents one or more commas.

comment-node clj/s

(comment-node s)

(comment-node prefix s)

Create node representing a comment with text s.

You may optionally specify a prefix of ";" or "#!", defaults is ";".

Argument s:

• must not include the prefix
• usually includes the trailing newline character, otherwise subsequent nodes will be on the comment line

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

(-> (n/comment-node "; my comment\n")
    n/string)
;; => ";; my comment\n"

(-> (n/comment-node "#!" "/usr/bin/env bb\n")
    n/string)
;; => "#!/usr/bin/env bb\n"

comment? clj/s

(comment? node)

Returns true if node is a comment.

deref-node clj/s

(deref-node children)

Create node representing the dereferencing of a form where children is either a sequence of nodes or a single node.

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

(-> (n/deref-node (n/token-node 'my-var))
    n/string)
;; => "@my-var"

;; specifying a sequence allows for whitespace between @ and form
(-> (n/deref-node [(n/spaces 2)
                   (n/token-node 'my-var)])
    n/string)
;; => "@  my-var"

eval-node clj/s

(eval-node children)

Create node representing an inline evaluation where children is either a sequence of nodes or a single node.

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

(-> (n/eval-node (n/list-node [(n/token-node 'inc)
                               (n/spaces 1)
                               (n/token-node 1)]))
    n/string)
;; => "#=(inc 1)"

;; specifying a sequence allows for whitespace between the
;; prefix and the form
(-> (n/eval-node [(n/spaces 3)
                  (n/list-node [(n/token-node 'inc)
                                (n/spaces 1)
                                (n/token-node 1)])])
    n/string)
;; => "#=   (inc 1)"

fn-node clj/s

(fn-node children)

Create node representing an anonymous function with children.

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

(-> (n/fn-node [(n/token-node '+)
                (n/spaces 1)
                (n/token-node 1)
                (n/spaces 1)
                (n/token-node '%1)])
    n/string)
;; => "#(+ 1 %1)"

forms-node clj/s

(forms-node children)

Create top-level node wrapping multiple children. The forms node is equivalent to an implicit do at the top-level.

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

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

inner? clj/s

(inner? node)

Returns true if node can have children.

integer-node clj/s

(integer-node value)

(integer-node value base)

Create node representing an integer value in base.

base defaults to 10.

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

(-> (n/integer-node 42)
    n/string)
;; => "42"

(-> (n/integer-node 31 2)
    n/string)
;; => "2r11111"

Note: the parser does not currently parse to integer-nodes, but they fully supported for output.

keyword-node clj/s

(keyword-node k)

(keyword-node k auto-resolved?)

Create a node representing a keyword k.

Optionally include auto-resolved?, which defaults to false.

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

;; unqualified keyword
(-> (n/keyword-node :kw)
    n/string)
;; => ":kw"

;; qualified keyword
(-> (n/keyword-node :my-prefix/kw)
    n/string)
;; => ":my-prefix/kw"

;; keyword auto-resolved to current ns
(-> (n/keyword-node :kw true)
    n/string)
;; => "::kw"

;; keyword auto-resolved to a namespace with given alias
(-> (n/keyword-node :ns-alias/kw true)
    n/string)
;; => "::ns-alias/kw"

keyword-node? clj/s

(keyword-node? n)

Returns true if n is a node representing a keyword.

leader-length clj/s

(leader-length node)

Returns number of characters before children for node.

length clj/s

(length node)

Return number of characters for the string version of node.

line-separated clj/s

(line-separated nodes)

Interleave nodes with newline nodes.

linebreak? clj/s

(linebreak? node)

Returns true if node represents one or more linebreaks.

list-node clj/s

(list-node children)

Create a node representing a list with children.

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

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

map-context-apply clj/s

(map-context-apply node map-qualifier)

Applies map-qualifier context to node

map-context-clear clj/s

(map-context-clear node)

Removes map-qualifier context for node

map-node clj/s

(map-node children)

Create a node representing a map with children.

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

(-> (n/map-node [(n/keyword-node :a)
                 (n/spaces 1)
                 (n/token-node 1)
                 (n/spaces 1)
                 (n/keyword-node :b)
                 (n/spaces 1)
                 (n/token-node 2)])
    (n/string))
;; => "{:a 1 :b 2}"

Note that rewrite-clj allows the, technically illegal, unbalanced map:

(-> (n/map-node [(n/keyword-node :a)])
    (n/string))
;; => "{:a}"

See docs on unbalanced maps.

Rewrite-clj also allows the, also technically illegal, map with duplicate keys:

(-> (n/map-node [(n/keyword-node :a)
                 (n/spaces 1)
                 (n/token-node 1)
                 (n/spaces 1)
                 (n/keyword-node :a)
                 (n/spaces 1)
                 (n/token-node 2)])
    (n/string))
;; => "{:a 1 :a 2}"

See docs on maps with duplicate keys.

map-qualifier-node clj/s

(map-qualifier-node auto-resolved? prefix)

Create a map qualifier node. The map qualifier node is a child node of namespaced-map-node.

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

;; qualified
(-> (n/map-qualifier-node false "my-prefix")
    n/string)
;; => ":my-prefix"

;; auto-resolved to current ns
(-> (n/map-qualifier-node true nil)
    n/string)
;; => "::"

;; auto-resolve to namespace with alias
(-> (n/map-qualifier-node true "my-ns-alias")
    n/string)
;; => "::my-ns-alias"

meta-node clj/s

(meta-node children)

(meta-node metadata data)

Create a node representing a form with metadata.

When creating manually, you can specify metadata and data and spacing between the 2 elems will be included:

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

(-> (n/meta-node (n/keyword-node :foo)
                 (n/vector-node [(n/token-node 1)]))
    n/string)
;; => "^:foo [1]"

(-> (n/meta-node (n/map-node [:foo (n/spaces 1) 42])
                 (n/vector-node [(n/token-node 1)]))
    n/string)
;; => "^{:foo 42} [1]"

When specifying a sequence of children, spacing is explicit:

(-> (n/meta-node [(n/keyword-node :foo)
                  (n/spaces 1)
                  (n/vector-node [(n/token-node 1)])])
    n/string)
;; => "^:foo [1]"

See also: raw-meta-node

namespaced-map-node clj/s

(namespaced-map-node children)

Create a namespaced map node with children.

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

(-> (n/namespaced-map-node [(n/map-qualifier-node true "my-ns-alias")
                            (n/spaces 1)
                            (n/map-node [(n/keyword-node :a)
                                         (n/spaces 1)
                                         (n/token-node 1)])])
    n/string)
;; => "#::my-ns-alias {:a 1}"

Map qualifier context is automatically applied to map keys for sexpr support.

See also map-qualifier-node and map-node.

newline-node clj/s

(newline-node s)

Create newline node of string s, where s is one or more linebreak characters.

newlines clj/s

(newlines n)

Create node representing n newline characters.

node? clj/s

(node? x)

Returns true if x is a rewrite-clj created node.

printable-only? clj/s

(printable-only? node)

Return true if node cannot be converted to an s-expression element.

quote-node clj/s

(quote-node children)

Create node representing a single quoted form where children is either a sequence of nodes or a single node.

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

(-> (n/quote-node (n/token-node 'sym))
    (n/string))
;; => "'sym"

;; specifying a sequence allows for whitespace between the
;; quote and the quoted
(-> (n/quote-node [(n/spaces 10)
                   (n/token-node 'sym1) ])
    n/string)
;; => "'          sym1"

raw-meta-node clj/s

(raw-meta-node children)

(raw-meta-node metadata data)

Create a node representing a form with metadata that renders to the reader syntax.

When creating manually, you can specify metadata and data and spacing between the 2 elems will be included:

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

(-> (n/raw-meta-node (n/keyword-node :foo)
                     (n/vector-node [(n/token-node 2)]))
     n/string)
;; => "#^:foo [2]"

(-> (n/raw-meta-node (n/map-node [:foo (n/spaces 1) 42])
                     (n/vector-node [(n/token-node 2)]))
    n/string)
;; => "#^{:foo 42} [2]"

When specifying a sequence of children, spacing is explicit:

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

(-> (n/raw-meta-node [(n/keyword-node :foo)
                      (n/spaces 1)
                      (n/vector-node [(n/token-node 2)])])
    n/string)
;; => "#^:foo [2]"

See also: meta-node

reader-macro-node clj/s

(reader-macro-node children)

(reader-macro-node macro-node form-node)

Create node representing a reader macro with macro-node and form-node or children.

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

;; here we call with macro-node and form-node
(-> (n/reader-macro-node (n/token-node 'my-macro)
                         (n/token-node 42))
    n/string)
;; => "#my-macro 42"

;; calling with a sequence of children gives us control over whitespace
(-> (n/reader-macro-node [(n/token-node 'my-macro)
                          (n/spaces 4)
                          (n/token-node 42)])
    n/string)
;; => "#my-macro    42"

regex-node clj/s

(regex-node pattern-string)

Create node representing a regex with pattern-string. Use same escape rules for pattern-string as you would for (re-pattern "pattern-string")

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

(-> (n/regex-node "my\\.lil.*regex")
    n/string)
;; => "#\"my\\.lil.*regex\""

replace-children clj/s

(replace-children node children)

Returns node replacing current children with children.

set-node clj/s

(set-node children)

Create a node representing a set with children.

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

(-> (n/set-node [(n/token-node 1)
                 (n/spaces 1)
                 (n/token-node 2)
                 (n/spaces 1)
                 (n/token-node 3)])
    n/string)
;; => "#{1 2 3}"

Note that rewrite-clj allows the, technically illegal, set with duplicate values:

(-> (n/set-node [(n/token-node 1)
                 (n/spaces 1)
                 (n/token-node 1)])
    (n/string))
;; => "#{1 1}"

See docs on sets with duplicate values.

sexpr clj/s

(sexpr node)

(sexpr node opts)

Return node converted to form.

Optional opts can specify:

• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

See docs for sexpr nuances.

sexpr-able? clj/s

(sexpr-able? node)

Return true if sexpr is supported for node's element type.

See related docs in user guide

sexprs clj/s

(sexprs nodes)

(sexprs nodes opts)

Return forms for nodes. Nodes that do not represent s-expression are skipped.

Optional opts can specify:

• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

See docs for sexpr nuances.

spaces clj/s

(spaces n)

Create node representing n spaces.

string clj/s

(string node)

Return the string version of node.

string-node clj/s

(string-node lines)

Create node representing a string value where lines can be a sequence of strings or a single string.

When lines is a sequence, the resulting node tag will be :multi-line, otherwise :token.

:multi-line refers to a single string in your source that appears over multiple lines, for example:

(def s "foo
          bar
            baz")

It does not apply to a string that appears on a single line that includes escaped newlines, for example:

(def s "foo\nbar\n\baz")

Naive examples (see example on escaping below):

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

(-> (n/string-node "hello")
    n/string)
;; => "\"hello\""

(-> (n/string-node ["line1" "" "line3"])
     n/string)
;; => "\"line1\n\nline3\""

This function was originally written to serve the rewrite-clj parser. Escaping and wrapping expectations are non-obvious.

• characters within strings are assumed to be escaped
• but the string should not wrapped with \"

Here's an example of conforming to these expectations for a string that has escape sequences. (Best to view this on cljdoc, docstring string escaping is confusing).

(require '[clojure.string :as string])

(defn pr-str-unwrapped [s]
  (apply str (-> s pr-str next butlast)))

(-> "hey \" man"
    pr-str-unwrapped
    n/string-node
    n/string)
;; => "\"hey \\\" man\""

To construct strings appearing on a single line, consider token-node. It will handle escaping for you.

symbol-node? clj/s

(symbol-node? n)

Returns true if n is a node representing a symbol.

syntax-quote-node clj/s

(syntax-quote-node children)

Create node representing a single syntax-quoted form where children is either a sequence of nodes or a single node.

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

(-> (n/syntax-quote-node (n/token-node 'map))
    n/string)
;; => "`map"

;; specifying a sequence allows for whitespace between the
;; syntax quote and the syntax quoted
(-> (n/syntax-quote-node [(n/spaces 3)
                          (n/token-node 'map)])
    n/string)
;; => "`   map"

tag clj/s

(tag node)

Returns keyword representing type of node.

token-node clj/s

(token-node value)

(token-node value string-value)

Create node for an unspecified token of value.

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

(-> (n/token-node 'sym) n/string)
;; => "sym"

(-> (n/token-node 42) n/string)
;; => "42"

(-> (n/token-node "astring") n/string)
;; => "\"astring\""

To construct strings appearing over multiple lines, see string-node.

uneval-node clj/s

(uneval-node children)

Create node representing an unevaled form with children.

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

(-> (n/uneval-node [(n/spaces 1)
                    (n/token-node 42)])
    n/string)
;; => "#_ 42"

unquote-node clj/s

(unquote-node children)

Create node representing a single unquoted form where children is either a sequence of nodes or a single node.

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

(-> (n/unquote-node (n/token-node 'my-var))
    n/string)
;; => "~my-var"

;; specifying a sequence allows for whitespace between the
;; unquote and the uquoted
(-> (n/unquote-node [(n/spaces 4)
                     (n/token-node 'my-var)])
    n/string)
;; => "~    my-var"

unquote-splicing-node clj/s

(unquote-splicing-node children)

Create node representing a single unquote-spliced form where children is either a sequence of nodes or a single node.

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

(-> (n/unquote-splicing-node (n/token-node 'my-var))
    n/string)
;; => "~@my-var"

;; specifying a sequence allows for whitespace between the
;; splicing unquote and the splicing unquoted
(-> (n/unquote-splicing-node [(n/spaces 2)
                              (n/token-node 'my-var)])
    n/string)
;; => "~@  my-var"

value clj/s deprecated

(value node)

DEPRECATED: Get first child as a pair of tag/sexpr (if inner node), or just the node's own sexpr. (use explicit analysis of children child-sexprs instead)

var-node clj/s

(var-node children)

Create node representing a var where children is either a sequence of nodes or a single node.

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

(-> (n/var-node (n/token-node 'my-var))
    n/string)
;; => "#'my-var"

;; specifying a sequence allows for whitespace between the
;; prefix and the var
(-> (n/var-node [(n/spaces 2)
                 (n/token-node 'my-var)])
    n/string)
;; => "#'  my-var"

vector-node clj/s

(vector-node children)

Create a node representing a vector with children.

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

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

whitespace-node clj/s

(whitespace-node s)

Create whitespace node of string s, where s is one or more space characters.

whitespace-nodes clj/s

(whitespace-nodes s)

Convert string s of whitespace to whitespace/newline nodes.

whitespace-or-comment? clj/s

(whitespace-or-comment? node)

Check whether the given node represents whitespace or comment.

whitespace? clj/s

(whitespace? node)

Returns true if node represents Clojure whitespace.