rewrite-cljc.zip — antq 0.9.0

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?

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-sexpr]]

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 zipper with key k set to value v when current node in zloc is a map node. Returns zipper with index k set to value v when current node in zloc is a sequence.

child-sexprs clj/s

(child-sexprs zloc)

Return s-expression of children of current node in zloc.

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 zipper with the current node in zloc replaced with the result of:

(f (s-expression node) args)

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

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 options)

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.

Set :track-position? in options to enable ones-based row/column tracking. See rewrite-cljc.zip/position.

NOTE: when position tracking is enabled, clojure.zip is not interchangeable with rewrite-cljc.zip, you must use rewrite-cljc.zip.

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]]).

Set :track-position? in options to enable ones-based row/column tracking. See rewrite-cljc.zip/position.

NOTE: when position tracking is enabled, clojure.zip is not interchangeable with rewrite-cljc.zip, you must use rewrite-cljc.zip.

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 the first node satisfying predicate p? seaching from the current node in zloc traversing by function f.

f defaults to rewrite-cljc.zip/right

find-depth-first clj/s

(find-depth-first zloc p?)

Return first node satisfying predicate p? searching depth-first from the current node in zloc.

find-last-by-pos clj/s

(find-last-by-pos zloc pos)

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

Return the last node spanning position pos that satisfies predicate p? searching depth-first from the current node in zloc.

NOTE: Does not ignore whitespace/comment nodes.

find-next clj/s

(find-next zloc p?)

(find-next zloc f p?)

Return the first node satisfying predicate p? searching one movement f from the current node in zloc traversing by function f.

f defaults to rewrite-cljc.zip/right

find-next-depth-first clj/s

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

Return the first node satisfying predicate p? searching depth-first from one node after the current node in zloc

find-next-tag clj/s

(find-next-tag zloc t)

(find-next-tag zloc f t)

Return the first node with tag t searching one movement f from the current node in zloc traversing by function 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 the first token node satisfying predicate p? searching from the current node in zloc traversing by function 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 the first token node with value v searching one movement f from the current node in zloc traversing by 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

find-tag clj/s

(find-tag zloc t)

(find-tag zloc f t)

Return the first node with tag t searching from the current node in zloc traversing by function f.

f defaults to rewrite-cljc.zip/right

find-tag-by-pos clj/s

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

Return the last node spanning position pos with tag t searching depth-first from the current node in zloc.

find-token clj/s

(find-token zloc p?)

(find-token zloc f p?)

Return the first token node satisfying predicate p? searching from the current node in zloc traversing by function f.

f defaults to rewrite-cljc.zip/right

find-value clj/s

(find-value zloc v)

(find-value zloc f v)

Return the first token node with value v searching one movement f from the current node in zloc traversing by 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

get clj/s

(get zloc k)

Returns value node mapped to key k when current node in zloc is a map node. Returns nth k value node when current node in zloc is a sequence node.

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 zipper with function f applied to all value nodes of current node in zloc. Current node must be a sequence node.

Iterates over:

• value nodes of maps
• each element of a seq

map-keys clj/s

(map-keys f zloc)

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

map-vals clj/s

(map-vals f zloc)

Returns zipper with function f applied to all value current node in zloc. Current node must be map node.

map? clj/s

(map? zloc)

Returns true if current node in zloc is a 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.

Set :track-position? in options to enable ones-based row/column tracking. See rewrite-cljc.zip/position.

NOTE: when position tracking is enabled, clojure.zip is not interchangeable with rewrite-cljc.zip, you must use rewrite-cljc.zip.

of-string clj/s

(of-string s)

(of-string s options)

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

Set :track-position? in options to enable ones-based row/column tracking. See rewrite-cljc.zip/position.

NOTE: when position tracking is enabled, clojure.zip is not interchangeable with rewrite-cljc.zip, you must use rewrite-cljc.zip.

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?, or all locations when p? is absent, and must return a valid zipper - modified or not.

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?, or all locations when p? is absent, and must return a valid zipper - modified or not.

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.

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 zipper with the current node in zloc replaced with value which will be coerced to a node if possible.

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 of current node in zloc.

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 child afterwards.

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).