rewrite-cljc.zip — antq 0.10.3

A rich API for navigating and updating Clojure/ClojureScripti/EDN source code via a zipper tree.

The zipper holds a tree of nodes representing source code. It also holds your current location while navigating through the tree and any pending changes you have made. Changes are applied back into the tree when invoking root functions.

Although they are preserved, whitespace and comment nodes are normally skipped when navigating through the tree. There are times when you will want to include whitespace and comment nodes, and as you see below, provisions are available to do so.

It is good to remember that while some function names convey mutation, we are never changing anything, we are instead returning modified copies.

Some conventions in the code and docstrings:

• zloc is the used as the argument name for our zipper
• "current node in zloc" is shorthand for: node at current location in zipper zloc

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

Create a zipper edn edn* of-string of-file

Move left right up down prev next leftmost rightmost

Move without skipping whitespace and comments left* right* up* down* prev* next* leftmost* rightmost*

Whitespace/comment aware skip skip skip-whitespace skip-whitespace-left

Test for whitespace whitespace? linebreak? whitespace-or-comment?

Test location leftmost? rightmost? end?

Test data type seq? list? vector? set? map? namespaced-map?

Find find find-next find-depth-first find-next-depth-first find-tag find-next-tag find-value find-next-value find-token find-next-token find-last-by-pos find-tag-by-pos

Inspect node position position-span tag length

Convert sexpr child-sexprs reapply-context

Update replace edit splice prefix suffix insert-right insert-left insert-child insert-space-left insert-space-right insert-newline-left insert-newline-right append-child remove remove-preserve-newline root

Update without whitespace treatment replace* edit* insert-left* insert-right* insert-child* append-child* remove*

Isolated update without changing location edit-node subedit-node subzip prewalk postwalk edit-> edit->> subedit-> subedit->>

Sequence operations map map-keys map-vals get assoc

Stringify string root-string

Output print print-root

->root-string clj/s deprecated

(->root-string zloc)

DEPRECATED. Renamed to root-string.

->string clj/s deprecated

(->string zloc)

DEPRECATED. Renamed to string.

append-child clj/s

(append-child zloc item)

Return zipper with item appended as last child of the current node in zloc. Will insert a space if necessary.

append-child* clj/s

(append-child* zloc item)

Raw version of append-child.

Returns zipper with item inserted as the rightmost child of the current node in zloc, without moving.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

append-newline clj/s deprecated

(append-newline zloc & [n])

DEPRECATED: renamed to insert-newline-right.

append-space clj/s deprecated

(append-space zloc & [n])

DEPRECATED: renamed to insert-space-right.

assoc clj/s

(assoc zloc k v)

Returns zloc with current node's k set to value v.

zloc location is unchanged.

k should be:

• a key for maps
• a zero-based index for sequences, an exception is thrown if index is out of bounds

NOTE: k will be compared against resolved keywords in maps. See docs for sexpr behavior on namespaced elements.

child-sexprs clj/s

(child-sexprs zloc)

Return s-expression (the Clojure forms) of children of current node in zloc.

See docs for sexpr nuances.

down clj/s

(down zloc)

Return zipper with location moved down to next non-whitespace/non-comment node in zloc.

down* clj/s

(down* zloc)

Raw version of down.

Returns zipper with the location at the leftmost child of current node in zloc, or nil if no children.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

edit clj/s

(edit zloc f & args)

Return zloc with the current node replaced with the result of:

(f (s-expression node) args)

f should return a node. The result of f will be coerced to a node if possible.

See docs for sexpr nuances.

edit* clj/s

(edit* zloc f & args)

Raw version of edit.

Returns zipper with value of (f current-node args) replacing current node in zloc

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

edit-> clj/s macro

(edit-> zloc & body)

Like ->, threads zloc through forms. The resulting zipper will be located at the same path (i.e. the same number of downwards and right movements from the root) as incoming zloc.

edit->> clj/s macro

(edit->> zloc & body)

Like ->>, threads zloc through forms. The resulting zipper will be located at the same path (i.e. the same number of downwards and right movements from the root) as incoming zloc.

edit-node clj/s

(edit-node zloc f)

Return zipper applying function f to zloc. The resulting zipper will be located at the same path (i.e. the same number of downwards and right movements from the root) incoming zloc.

edn clj/s

(edn node)

(edn node opts)

Create and return zipper from Clojure/ClojureScript/EDN node (likely parsed by [[rewrite-cljc.parse]]), and move to the first non-whitespace/non-comment child. If node is not forms node, is wrapped in forms node for a consistent root.

Optional opts can specify:

• :track-position? set to true to enable ones-based row/column tracking, see docs on position tracking.
• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

edn* clj/s

(edn* node)

(edn* node {:keys [track-position?]})

Create and return zipper from Clojure/ClojureScript/EDN node (likely parsed by [[rewrite-cljc.parse]]).

Optional opts can specify:

• :track-position? set to true to enable ones-based row/column tracking, see docs on position tracking.
• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

end? clj/s

(end? zloc)

Return true if zloc is at end of depth-first traversal.

find clj/s

(find zloc p?)

(find zloc f p?)

Return zloc located to the first node satisfying predicate p? else nil. Search starts at the current node and continues via movement function f.

f defaults to rewrite-cljc.zip/right

find-depth-first clj/s

(find-depth-first zloc p?)

Return zloc located to the first node satisfying predicate p? else nil. Search is depth-first from the current node.

find-last-by-pos clj/s

(find-last-by-pos zloc pos)

(find-last-by-pos zloc pos p?)

Return zloc located to the last node spanning position pos that satisfies predicate p? else nil. Search is depth-first from the current node.

NOTE: Does not ignore whitespace/comment nodes.

find-next clj/s

(find-next zloc p?)

(find-next zloc f p?)

Return zloc located to the next node satisfying predicate p? else nil. Search starts one movement f from the current node continues via f.

f defaults to rewrite-cljc.zip/right

find-next-depth-first clj/s

(find-next-depth-first zloc p?)

Return zloc located to next node satisfying predicate p? else nil. Search starts depth-first after the current node.

find-next-tag clj/s

(find-next-tag zloc t)

(find-next-tag zloc f t)

Return zloc located to the next node with tag t else nil. Search starts one movement f after the current node and continues via f.

f defaults to rewrite-cljc.zip/right

find-next-token clj/s

(find-next-token zloc p?)

(find-next-token zloc f p?)

Return zloc location to the next token node satisfying predicate p? else nil. Search starts one movement f after the current node and continues via f.

f defaults to rewrite-cljc.zip/right

find-next-value clj/s

(find-next-value zloc v)

(find-next-value zloc f v)

Return zloc located to the next token node that sexpresses to v else nil. Search starts one movement f from the current location, and continues via f.

v can be a single value or a set. When v is a set matches on any value in set.

f defaults to rewrite-cljc.zip/right in short form call.

See docs for sexpr nuances.

find-tag clj/s

(find-tag zloc t)

(find-tag zloc f t)

Return zloc located to the first node with tag t else nil. Search starts at the current node and continues via movement function f.

f defaults to rewrite-cljc.zip/right

find-tag-by-pos clj/s

(find-tag-by-pos zloc pos t)

Return zloc located to the last node spanning position pos with tag t else nil. Search is depth-first from the current node.

find-token clj/s

(find-token zloc p?)

(find-token zloc f p?)

Return zloc located to the the first token node satisfying predicate p?. Search starts at the current node and continues via movement function f.

f defaults to rewrite-cljc.zip/right

find-value clj/s

(find-value zloc v)

(find-value zloc f v)

Return zloc located to the first token node that sexpresses to v else nil. Search starts from the current node and continues via movement function f.

v can be a single value or a set. When v is a set, matches on any value in set.

f defaults to rewrite-cljc.zip/right in short form call.

See docs for sexpr nuances.

get clj/s

(get zloc k)

Returns zloc located to map key node's sexpr value matching k else nil.

k should be:

• a key for maps
• a zero-based index for sequences

NOTE: k will be compared against resolved keywords in maps. See docs for sexpr behavior on namespaced elements.

insert-child clj/s

(insert-child zloc item)

Return zipper with item inserted as the first child of the current node in zloc.

insert-child* clj/s

(insert-child* zloc item)

Raw version of insert-child.

Returns zipper with item inserted as the leftmost child of the current node in zloc, without moving location.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

insert-left clj/s

(insert-left zloc item)

Return zipper with item inserted to the left of the current node in zloc. Will insert a space if necessary.

insert-left* clj/s

(insert-left* zloc item)

Raw version of insert-left.

Returns zipper with item inserted as the left sibling of current node in zloc, without moving location.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

insert-newline-left clj/s

(insert-newline-left zloc)

(insert-newline-left zloc n)

Return zipper with n newlines node inserted to the left of the current node in zloc. n defaults to 1.

insert-newline-right clj/s

(insert-newline-right zloc)

(insert-newline-right zloc n)

Return zipper with n newlines node inserted to the right of the current node in zloc. n defaults to 1.

insert-right clj/s

(insert-right zloc item)

Return zipper with item inserted to the right of the current node in zloc. Will insert a space if necessary.

insert-right* clj/s

(insert-right* zloc item)

Raw version of insert-right.

Returns zipper with item inserted as the right sibling of the current node in zloc, without moving location.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

insert-space-left clj/s

(insert-space-left zloc)

(insert-space-left zloc n)

Return zipper with n space whitespace node inserted to the left of the current node in zloc. n defaults to 1.

insert-space-right clj/s

(insert-space-right zloc)

(insert-space-right zloc n)

Return zipper with n space whitespace node inserted to the right of the current node in zloc. n defaults to 1.

left clj/s

(left zloc)

Return zipper with location moved left to next non-whitespace/non-comment node in zloc.

left* clj/s

(left* zloc)

Raw version of left.

Returns zipper with location at the left sibling of the current node in zloc, or nil.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

leftmost clj/s

(leftmost zloc)

Return zipper with location moved to the leftmost non-whitespace/non-comment node in zloc.

leftmost* clj/s

(leftmost* zloc)

Raw version of leftmost.

Returns zipper with location at the leftmost sibling of the current node in zloc, or self.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

leftmost? clj/s

(leftmost? zloc)

Return true if at leftmost non-whitespace/non-comment node in zloc.

length clj/s

(length zloc)

Return length of printable string of current node in zloc.

linebreak? clj/s

(linebreak? zloc)

Returns true when the current node in zloc is a linebreak.

list? clj/s

(list? zloc)

Returns true if current node in zloc is a list.

map clj/s

(map f zloc)

Returns zloc with function f applied to all nodes of the current node. Current node must be a sequence node. Equivalent to rewrite-cljc.zip/map-vals for maps.

zloc location is unchanged.

f arg is zloc positioned at

• value nodes for maps
• each element of a seq and is should return:
• an updated zloc with zloc positioned at edited node
• a falsey value to leave value node unchanged

Folks typically use rewrite-cljc.zip/edit for f.

map-keys clj/s

(map-keys f zloc)

Returns zloc with function f applied to all key nodes of the current node. Current node must be map node.

zloc location is unchanged.

f arg is zloc positioned at key node and should return:

• an updated zloc with zloc positioned at key node
• a falsey value to leave value node unchanged

Folks typically use rewrite-cljc.zip/edit for f.

map-vals clj/s

(map-vals f zloc)

Returns zloc with function f applied to each value node of the current node. Current node must be map node.

zloc location is unchanged.

f arg is zloc positioned at value node and should return:

• an updated zloc with zloc positioned at value node
• a falsey value to leave value node unchanged

Folks typically use rewrite-cljc.zip/edit for f.

map? clj/s

(map? zloc)

Returns true if current node in zloc is a map.

namespaced-map? clj/s

(namespaced-map? zloc)

Returns true if the current node in zloc is a namespaced map.

next clj/s

(next zloc)

Return zipper with location moved to the next depth-first non-whitespace/non-comment node in zloc.

next* clj/s

(next* {:keys [end?] :as zloc})

Raw version of next.

Returns zipper with location at the next depth-first location in the hierarchy in zloc. When reaching the end, returns a distinguished zipper detectable via end?. If already at the end, stays there.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

node clj/s

(node zloc)

Returns the current node in zloc.

of-file clj

(of-file f)

(of-file f options)

Create and return zipper from all forms in Clojure/ClojureScript/EDN File f.

Optional opts can specify:

• :track-position? set to true to enable ones-based row/column tracking, see docs on position tracking.
• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

of-string clj/s

(of-string s)

(of-string s opts)

Create and return zipper from all forms in Clojure/ClojureScript/EDN string s.

Optional opts can specify:

• :track-position? set to true to enable ones-based row/column tracking, see docs on position tracking.
• :auto-resolve specify a function to customize namespaced element auto-resolve behavior, see docs on namespaced elements

position clj/s

(position zloc)

Returns the ones-based [row col] of the start of the current node in zloc.

position-span clj/s

(position-span zloc)

Returns the ones-based [[start-row start-col] [end-row end-col]] of the current node in zloc.

postwalk clj/s

(postwalk zloc f)

(postwalk zloc p? f)

Return zipper modified by an isolated depth-first post-order traversal. Traversal starts at the current node in zloc and continues to the end of the isolated sub-tree. Function f is called on the zipper locations satisfying predicate p?, and must return a valid zipper - modified or not.

When p? is not specified f is called all locations.

Note that by default a newly created zipper automatically navigates to the first non-whitespace node. If you want to be sure to walk all forms in a zipper, you'll want to navigate one up prior to your walk:

(-> (zip/of-string "my clojure forms")
    zip/up
    (zip/postwalk ...))

WARNING: when function f changes the location in the zipper, normal traversal will be affected.

prefix clj/s

(prefix zloc s)

Return zipper with the current node in zloc prefixed with string s. Operates on token node or a multi-line node, else exception is thrown. When multi-line, first line is prefixed.

prepend-newline clj/s deprecated

(prepend-newline zloc & [n])

DEPRECATED: renamed to insert-newline-left.

prepend-space clj/s deprecated

(prepend-space zloc & [n])

DEPRECATED: renamed to insert-space-left.

prev clj/s

(prev zloc)

Return zipper with location moved to the previous depth-first non-whitespace/non-comment node in zloc.

prev* clj/s

(prev* zloc)

Raw version of prev.

Returns zipper with location at the previous depth-first location in the hierarchy in zloc. If already at the root, returns nil.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

prewalk clj/s

(prewalk zloc f)

(prewalk zloc p? f)

Return zipper modified by an isolated depth-first pre-order traversal. Traversal starts at the current node in zloc and continues to the end of the isolated sub-tree. Function f is called on the zipper locations satisfying predicate p? and must return a valid zipper - modified or not.

When p? is not specified f is called all locations.

Note that by default a newly created zipper automatically navigates to the first non-whitespace node. If you want to be sure to walk all forms in a zipper, you'll want to navigate one up prior to your walk:

(-> (zip/of-string "my clojure forms")
    zip/up
    (zip/prewalk ...))

WARNING: when function f changes the location in the zipper, normal traversal will be affected.

print clj/s

(print zloc & [writer])

Print current node in zloc.

NOTE: Optional writer is currently ignored for ClojureScript.

print-root clj/s

(print-root zloc & [writer])

Zip up and print zloc from root node.

NOTE: Optional writer is currently ignored for ClojureScript.

reapply-context clj/s

(reapply-context zloc)

Returns zloc with namespaced map sexpr context to all symbols and keywords reapplied from current location downward.

Keywords and symbols:

• that are keys in a namespaced map will have namespaced map context applied
• otherwise will have any namespaced map context removed

You should only need to use this function if:

• you care about sexpr on keywords and symbols
• and you are moving keywords and symbols from a namespaced map to some other location.

remove clj/s

(remove zloc)

Return zipper with current node in zloc removed. Returned zipper location is moved to the first non-whitespace node preceding removed node in a depth-first walk. Removes whitespace appropriately.

• [1 |2 3] => [|1 3]
• [1 |2] => [|1]
• [|1 2] => |[2]
• [|1] => |[]
• [ |1 ] => |[]
• [1 [2 3] |4] => [1 [2 |3]]
• [|1 [2 3] 4] => |[[2 3] 4]

If the removed node is at the rightmost location, both preceding and trailing spaces are removed, otherwise only trailing spaces are removed. This means that a following element (no matter whether on the same line or not) will end up in the same position (line/column) as the removed one, unless a comment lies between the original node and the neighbour.

remove* clj/s

(remove* zloc)

Raw version of remove.

Returns zipper with current node in zloc removed, with location at node that would have preceded it in a depth-first walk.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

remove-preserve-newline clj/s

(remove-preserve-newline zloc)

Same as remove but preserves newlines.

replace clj/s

(replace zloc value)

Return zloc with the current node replaced by value. If value is not already a node, an attempt will be made to coerce it to one.

replace* clj/s

(replace* zloc node)

Raw version of replace.

Returns zipper with node replacing current node in zloc, without moving location.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

right clj/s

(right zloc)

Return zipper with location moved right to next non-whitespace/non-comment node in zloc.

right* clj/s

(right* zloc)

Raw version of right.

Returns zipper with location at the right sibling of the current node in zloc, or nil.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

rightmost clj/s

(rightmost zloc)

Return zipper with location moved to the rightmost non-whitespace/non-comment node in zloc.

rightmost* clj/s

(rightmost* zloc)

Raw version of rightmost.

Returns zipper with location at the rightmost sibling of the current node in zloc, or self.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

rightmost? clj/s

(rightmost? zloc)

Return true if at rightmost non-whitespace/non-comment node in zloc.

root clj/s

(root {:keys [end?] :as zloc})

Zips all the way up zloc and returns zipper at the root node, reflecting any changes.

root-string clj/s

(root-string zloc)

Return string representing the zipped-up zloc zipper.

seq? clj/s

(seq? zloc)

Returns true if current node in zloc is a sequence.

set? clj/s

(set? zloc)

Returns true if current node in zloc is a set.

sexpr clj/s

(sexpr zloc)

Return s-expression (the Clojure form) of current node in zloc.

See docs for sexpr nuances.

skip clj/s

(skip f p? zloc)

Return zipper with location moved to first location not satisfying predicate p? starting from the node in zloc and traversing by function f.

skip-whitespace clj/s

(skip-whitespace zloc)

(skip-whitespace f zloc)

Return zipper with location moved to first non-whitespace/non-comment starting from current node in zloc and traversing by function f.

f defaults to rewrite-cljc.zip/right

skip-whitespace-left clj/s

(skip-whitespace-left zloc)

Return zipper with location moved to first non-whitespace/non-comment starting from current node in zloc traversing left.

splice clj/s

(splice zloc)

Return zipper with the children of the current node in zloc merged into itself. (akin to Clojure's unquote-splicing macro: ~@...).

• if the node is not one that can have children, no modification will be performed.
• if the node has no or only whitespace children, it will be removed.
• otherwise, splicing will be performed, moving the zipper to the first non-whitespace spliced child node.

For example, given [[1 2 3] 4 5 6], if zloc is located at vector [1 2 3], a splice will result in raising the vector's children up [1 2 3 4 5 6] and locating the zipper at node 1.

string clj/s

(string zloc)

Return string representing the current node in zloc.

subedit-> clj/s macro

(subedit-> zloc & body)

Like ->, threads zloc, as an isolated sub-tree through forms, then zips up to, and locates at, the root of the modified sub-tree.

subedit->> clj/s macro

(subedit->> zloc & body)

Like ->. Threads zloc, as an isolated sub-tree through forms, then zips up to, and locates at, the root of the modified sub-tree.

subedit-node clj/s

(subedit-node zloc f)

Return zipper replacing current node in zloc with result of f applied to said node as an isolated sub-tree. The resulting zipper will be located on the root of the modified sub-tree.

subzip clj/s

(subzip zloc)

Create and return a zipper whose root is the current node in zloc.

suffix clj/s

(suffix zloc s)

Return zipper with the current node in zloc suffixed with string s. Operates on token node or a multi-line node, else exception is thrown. When multi-line, last line is suffixed.

tag clj/s

(tag zloc)

Return tag of current node in zloc.

up clj/s

(up zloc)

Return zipper with location moved up to next non-whitespace/non-comment node in zloc.

up* clj/s

(up* zloc)

Raw version of up.

Returns zipper with the location at the parent of current node in zloc, or nil if at the top.

NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.

value clj/s deprecated

(value zloc)

DEPRECATED. Return a tag/s-expression pair for inner nodes, or the s-expression itself for leaves.

vector? clj/s

(vector? zloc)

Returns true if current node in zloc is a vector.

whitespace-or-comment? clj/s

(whitespace-or-comment? zloc)

Returns true when current node in zloc is whitespace or a comment.

whitespace? clj/s

(whitespace? zloc)

Returns true when the current the node in zloc is a Clojure whitespace (which includes the comma).