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 zipperzloc
" 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
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 zloc)
DEPRECATED. Renamed to root-string
.
DEPRECATED. Renamed to [[root-string]].
(->string zloc)
DEPRECATED. Renamed to string
.
DEPRECATED. Renamed to [[string]].
(append-child zloc item)
Return zipper with item
appended as last child of the current node in zloc
.
Will insert a space if necessary.
Return zipper with `item` appended as last child of the current node in `zloc`. Will insert a space if necessary.
(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.
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 zloc & [n])
DEPRECATED: renamed to insert-newline-right
.
DEPRECATED: renamed to [[insert-newline-right]].
(append-space zloc & [n])
DEPRECATED: renamed to insert-space-right
.
DEPRECATED: renamed to [[insert-space-right]].
(assoc zloc k v)
Returns zloc
with current node's k
set to value v
.
zloc
location is unchanged.
k
should be:
NOTE: k
will be compared against resolved keywords in maps.
See docs for sexpr behavior on namespaced elements.
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](/doc/01-introduction.adoc#namespaced-elements).
(child-sexprs zloc)
Return s-expression (the Clojure forms) of children of current node in zloc
.
See docs for sexpr nuances.
Return s-expression (the Clojure forms) of children of current node in `zloc`. See docs for [sexpr nuances](/doc/01-introduction.adoc#sexpr-nuances).
(down zloc)
Return zipper with location moved down to next non-whitespace/non-comment node in zloc
.
Return zipper with location moved down to next non-whitespace/non-comment node in `zloc`.
(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.
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 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.
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](/doc/01-introduction.adoc#sexpr-nuances).
(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.
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-> 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
.
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->> 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
.
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 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
.
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 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 elementsCreate 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](/doc/01-introduction.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-introduction.adoc#namespaced-elements)
(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 elementsCreate 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](/doc/01-introduction.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-introduction.adoc#namespaced-elements)
(end? zloc)
Return true if zloc
is at end of depth-first traversal.
Return true if `zloc` is at end of depth-first traversal.
(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
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 zloc p?)
Return zloc
located to the first node satisfying predicate p?
else nil
.
Search is depth-first from the current node.
Return `zloc` located to the first node satisfying predicate `p?` else `nil`. Search is depth-first from the current node.
(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.
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 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
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 zloc p?)
Return zloc
located to next node satisfying predicate p?
else nil
.
Search starts depth-first after the current node.
Return `zloc` located to next node satisfying predicate `p?` else `nil`. Search starts depth-first after the current node.
(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
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 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
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 zloc v)
(find-next-value zloc f v)
Return zloc
located to the next token node that sexpr
esses 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.
Return `zloc` located to the next token node that `sexpr`esses 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](/doc/01-introduction.adoc#sexpr-nuances).
(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
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 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.
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 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
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 zloc v)
(find-value zloc f v)
Return zloc
located to the first token node that sexpr
esses 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.
Return `zloc` located to the first token node that `sexpr`esses 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](/doc/01-introduction.adoc#sexpr-nuances).
(get zloc k)
Returns zloc
located to map key node's sexpr value matching k
else nil
.
k
should be:
NOTE: k
will be compared against resolved keywords in maps.
See docs for sexpr behavior on namespaced elements.
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](/doc/01-introduction.adoc#namespaced-elements).
(insert-child zloc item)
Return zipper with item
inserted as the first child of the current node in zloc
.
Return zipper with `item` inserted as the first child of the current node in `zloc`.
(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.
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 zloc item)
Return zipper with item
inserted to the left of the current node in zloc
.
Will insert a space if necessary.
Return zipper with `item` inserted to the left of the current node in `zloc`. Will insert a space if necessary.
(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.
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 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.
Return zipper with `n` newlines node inserted to the left of the current node in `zloc`. `n` defaults to 1.
(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.
Return zipper with `n` newlines node inserted to the right of the current node in `zloc`. `n` defaults to 1.
(insert-right zloc item)
Return zipper with item
inserted to the right of the current node in zloc
.
Will insert a space if necessary.
Return zipper with `item` inserted to the right of the current node in `zloc`. Will insert a space if necessary.
(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.
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 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.
Return zipper with `n` space whitespace node inserted to the left of the current node in `zloc`. `n` defaults to 1.
(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.
Return zipper with `n` space whitespace node inserted to the right of the current node in `zloc`. `n` defaults to 1.
(left zloc)
Return zipper with location moved left to next non-whitespace/non-comment node in zloc
.
Return zipper with location moved left to next non-whitespace/non-comment node in `zloc`.
(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.
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 zloc)
Return zipper with location moved to the leftmost non-whitespace/non-comment node in zloc
.
Return zipper with location moved to the leftmost non-whitespace/non-comment node in `zloc`.
(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.
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? zloc)
Return true if at leftmost non-whitespace/non-comment node in zloc
.
Return true if at leftmost non-whitespace/non-comment node in `zloc`.
(length zloc)
Return length of printable string of current node in zloc
.
Return length of printable string of current node in `zloc`.
(linebreak? zloc)
Returns true when the current node in zloc
is a linebreak.
Returns true when the current node in `zloc` is a linebreak.
(list? zloc)
Returns true if current node in zloc
is a list.
Returns true if current node in `zloc` is a list.
(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
Folks typically use rewrite-cljc.zip/edit
for f
.
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 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:
Folks typically use rewrite-cljc.zip/edit
for f
.
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 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:
Folks typically use rewrite-cljc.zip/edit
for f
.
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? zloc)
Returns true if current node in zloc
is a map.
Returns true if current node in `zloc` is a map.
(namespaced-map? zloc)
Returns true if the current node in zloc
is a namespaced map.
Returns true if the current node in `zloc` is a namespaced map.
(next zloc)
Return zipper with location moved to the next depth-first non-whitespace/non-comment node in zloc
.
Return zipper with location moved to the next depth-first non-whitespace/non-comment node in `zloc`.
(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.
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 zloc)
Returns the current node in zloc
.
Returns the current node in `zloc`.
(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 elementsCreate 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](/doc/01-introduction.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-introduction.adoc#namespaced-elements)
(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 elementsCreate 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](/doc/01-introduction.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-introduction.adoc#namespaced-elements)
(position zloc)
Returns the ones-based [row col]
of the start of the current node in zloc
.
Returns the ones-based `[row col]` of the start of the current node in `zloc`.
(position-span zloc)
Returns the ones-based [[start-row start-col] [end-row end-col]]
of the current node in zloc
.
Returns the ones-based `[[start-row start-col] [end-row end-col]]` of the current node in `zloc`.
(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.
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: ```Clojure (-> (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 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.
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 zloc & [n])
DEPRECATED: renamed to insert-newline-left
.
DEPRECATED: renamed to [[insert-newline-left]].
(prepend-space zloc & [n])
DEPRECATED: renamed to insert-space-left
.
DEPRECATED: renamed to [[insert-space-left]].
(prev zloc)
Return zipper with location moved to the previous depth-first non-whitespace/non-comment node in zloc
.
Return zipper with location moved to the previous depth-first non-whitespace/non-comment node in `zloc`.
(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.
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 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.
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: ```Clojure (-> (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 zloc & [writer])
Print current node in zloc
.
NOTE: Optional writer
is currently ignored for ClojureScript.
Print current node in `zloc`. NOTE: Optional `writer` is currently ignored for ClojureScript.
(print-root zloc & [writer])
Zip up and print zloc
from root node.
NOTE: Optional writer
is currently ignored for ClojureScript.
Zip up and print `zloc` from root node. NOTE: Optional `writer` is currently ignored for ClojureScript.
(reapply-context zloc)
Returns zloc
with namespaced map sexpr context to all symbols and keywords reapplied from current location downward.
Keywords and symbols:
You should only need to use this function if:
sexpr
on keywords and symbolsReturns `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 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.
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* 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.
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 zloc)
Same as remove
but preserves newlines.
Same as [[remove]] but preserves newlines.
(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.
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* 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.
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 zloc)
Return zipper with location moved right to next non-whitespace/non-comment node in zloc
.
Return zipper with location moved right to next non-whitespace/non-comment node in `zloc`.
(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.
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 zloc)
Return zipper with location moved to the rightmost non-whitespace/non-comment node in zloc
.
Return zipper with location moved to the rightmost non-whitespace/non-comment node in `zloc`.
(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.
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? zloc)
Return true if at rightmost non-whitespace/non-comment node in zloc
.
Return true if at rightmost non-whitespace/non-comment node in `zloc`.
(root {:keys [end?] :as zloc})
Zips all the way up zloc
and returns zipper at the root node, reflecting any changes.
Zips all the way up `zloc` and returns zipper at the root node, reflecting any changes.
(root-string zloc)
Return string representing the zipped-up zloc
zipper.
Return string representing the zipped-up `zloc` zipper.
(seq? zloc)
Returns true if current node in zloc
is a sequence.
Returns true if current node in `zloc` is a sequence.
(set? zloc)
Returns true if current node in zloc
is a set.
Returns true if current node in `zloc` is a set.
(sexpr zloc)
Return s-expression (the Clojure form) of current node in zloc
.
See docs for sexpr nuances.
Return s-expression (the Clojure form) of current node in `zloc`. See docs for [sexpr nuances](/doc/01-introduction.adoc#sexpr-nuances).
(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
.
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 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
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 zloc)
Return zipper with location moved to first non-whitespace/non-comment starting from current node in zloc
traversing left.
Return zipper with location moved to first non-whitespace/non-comment starting from current node in `zloc` traversing left.
(splice zloc)
Return zipper with the children of the current node in zloc
merged into itself.
(akin to Clojure's unquote-splicing
macro: ~@...
).
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
.
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 zloc)
Return string representing the current node in zloc
.
Return string representing the current node in `zloc`.
(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.
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->> 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.
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 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.
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 zloc)
Create and return a zipper whose root is the current node in zloc
.
Create and return a zipper whose root is the current node in `zloc`.
(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.
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 zloc)
Return tag of current node in zloc
.
Return tag of current node in `zloc`.
(up zloc)
Return zipper with location moved up to next non-whitespace/non-comment node in zloc
.
Return zipper with location moved up to next non-whitespace/non-comment node in `zloc`.
(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.
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 zloc)
DEPRECATED. Return a tag/s-expression pair for inner nodes, or the s-expression itself for leaves.
DEPRECATED. Return a tag/s-expression pair for inner nodes, or the s-expression itself for leaves.
(vector? zloc)
Returns true if current node in zloc
is a vector.
Returns true if current node in `zloc` is a vector.
(whitespace-or-comment? zloc)
Returns true when current node in zloc
is whitespace or a comment.
Returns true when current node in `zloc` is whitespace or a comment.
(whitespace? zloc)
Returns true when the current the node in zloc
is a Clojure whitespace (which includes the comma).
Returns true when the current the node in `zloc` is a Clojure whitespace (which includes the comma).
cljdoc is a website building & hosting documentation for Clojure/Script libraries
× close