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-able?
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*
Update without changing location
edit-node
edit->
edit->>
Isolated update without changing location
subedit-node
subzip
prewalk
postwalk
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-able?]] [[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*]] **Update without changing location** [[edit-node]] [[edit->]] [[edit->>]] **Isolated update without changing location** [[subedit-node]] [[subzip]] [[prewalk]] [[postwalk]] [[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
inserted as the last child of the current node in zloc
, without moving.
Will insert a space if necessary.
Return zipper with `item` inserted as the last child of the current node in `zloc`, without moving. 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)
(append-newline zloc n)
DEPRECATED: renamed to insert-newline-right
.
DEPRECATED: renamed to [[insert-newline-right]].
(append-space zloc)
(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-user-guide.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-user-guide.adoc#sexpr-nuances).
(down zloc)
Return zipper with location moved down to the first non-whitespace/non-comment child node of the current node in zloc
, or nil if no applicable children.
Return zipper with location moved down to the first non-whitespace/non-comment child node of the current node in `zloc`, or nil if no applicable children.
(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:
(apply f (s-expr current-node) args)
The result of f
, if not already a node, will be coerced to a node if possible.
See docs for sexpr nuances.
Return `zloc` with the current node replaced with the result of: `(apply f (s-expr current-node) args)` The result of `f`, if not already a node, will be coerced to a node if possible. See docs for [sexpr nuances](/doc/01-user-guide.adoc#sexpr-nuances).
(edit* zloc f & args)
Raw version of edit
.
Returns zipper with value of (apply f current-node args)
replacing current node in zloc
.
The result of f
should be a rewrite-clj node.
NOTE: This function does not skip, nor provide any special handling for whitespace/comment nodes.
Raw version of [[edit]]. Returns zipper with value of `(apply f current-node args)` replacing current node in `zloc`. The result of `f` should be a rewrite-clj node. 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
.
See also subedit->
for an isolated edit.
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`. See also [[subedit->]] for an isolated edit.
(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
.
See also subedit->>
for an isolated edit.
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`. See also [[subedit->>]] for an isolated edit.
(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
.
See also subedit-node
for an isolated edit.
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`. See also [[subedit-node]] for an isolated edit.
(edn node)
(edn node opts)
Create and return zipper from Clojure/ClojureScript/EDN node
(likely parsed by [[rewrite-clj.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-clj.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-user-guide.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
(edn* node)
(edn* node opts)
Create and return zipper from Clojure/ClojureScript/EDN node
(likely parsed by [[rewrite-clj.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-clj.parse]]). Optional `opts` can specify: - `:track-position?` set to `true` to enable ones-based row/column tracking, see [docs on position tracking](/doc/01-user-guide.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.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-clj.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-clj.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 and continues via f
.
f
defaults to rewrite-clj.zip/right
Return `zloc` located to the next node satisfying predicate `p?` else `nil`. Search starts one movement `f` from the current node and continues via `f`. `f` defaults to [[rewrite-clj.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-clj.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-clj.zip/right]]
(find-next-token zloc p?)
(find-next-token zloc f p?)
Return zloc
located 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-clj.zip/right
Return `zloc` located 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-clj.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-clj.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-clj.zip/right]] in short form call. See docs for [sexpr nuances](/doc/01-user-guide.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-clj.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-clj.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-clj.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-clj.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-clj.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-clj.zip/right]] in short form call. See docs for [sexpr nuances](/doc/01-user-guide.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-user-guide.adoc#namespaced-elements).
(insert-child zloc item)
Return zipper with item
inserted as the first child of the current node in zloc
, without moving location.
Return zipper with `item` inserted as the first child of the current node in `zloc`, without moving location.
(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
, without moving location.
Will insert a space if necessary.
Return zipper with `item` inserted to the left of the current node in `zloc`, without moving location. 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
, without moving location.
n
defaults to 1.
Return zipper with `n` newlines node inserted to the left of the current node in `zloc`, without moving location. `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
, without moving location.
n
defaults to 1.
Return zipper with `n` newlines node inserted to the right of the current node in `zloc`, without moving location. `n` defaults to 1.
(insert-right zloc item)
Return zipper with item
inserted to the right of the current node in zloc
, without moving location.
Will insert a space if necessary.
Return zipper with `item` inserted to the right of the current node in `zloc`, without moving location. 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
, without moving location.
n
defaults to 1.
Return zipper with `n` space whitespace node inserted to the left of the current node in `zloc`, without moving location. `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
, without moving location.
n
defaults to 1.
Return zipper with `n` space whitespace node inserted to the right of the current node in `zloc`, without moving location. `n` defaults to 1.
(left zloc)
Return zipper with location moved left to next non-whitespace/non-comment sibling of current node in zloc
.
Return zipper with location moved left to next non-whitespace/non-comment sibling of current 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 sibling of current node in zloc
.
Return zipper with location moved to the leftmost non-whitespace/non-comment sibling of current 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 sibling node in zloc
.
Return true if at leftmost non-whitespace/non-comment sibling 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-clj.zip/map-vals
for maps.
zloc
location is unchanged.
f
arg is zloc positioned at
Folks typically use rewrite-clj.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-clj.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-clj.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-clj.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-clj.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-clj.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-clj.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
.
End can be detected with end?
, if already at end, stays there.
Return zipper with location moved to the next depth-first non-whitespace/non-comment node in `zloc`. End can be detected with [[end?]], if already at end, stays there.
(next* 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 opts)
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-user-guide.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.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-user-guide.adoc#position-tracking). - `:auto-resolve` specify a function to customize namespaced element auto-resolve behavior, see [docs on namespaced elements](/doc/01-user-guide.adoc#namespaced-elements)
(position zloc)
Returns the ones-based [row col]
of the start of the current node in zloc
.
Throws if zloc
was not created with position tracking.
Returns the ones-based `[row col]` of the start of the current node in `zloc`. Throws if `zloc` was not created with [position tracking](/doc/01-user-guide.adoc#position-tracking).
(position-span zloc)
Returns the ones-based [[start-row start-col] [end-row end-col]]
of the current node in zloc
.
end-col
is exclusive.
Throws if zloc
was not created with position tracking.
Returns the ones-based `[[start-row start-col] [end-row end-col]]` of the current node in `zloc`. `end-col` is exclusive. Throws if `zloc` was not created with [position tracking](/doc/01-user-guide.adoc#position-tracking).
(postwalk zloc f)
(postwalk zloc p? f)
Return zipper modified by an isolated depth-first post-order traversal.
Pre-order traversal visits children before root.
For example, traversal order of (1 (2 3 (4 5) 6 (7 8)) 9)
is:
1
2
3
4
5
(4 5)
6
7
8
(7 8)
(2 3 (4 5) 6 (7 8))
9
(1 (2 3 (4 5) 6 (7 8)) 9)
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 either
f
changes the location in the zipper, normal traversal will be affected.When p?
is not specified f
is called on 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 ...))
See docs on sub editing.
Return zipper modified by an isolated depth-first post-order traversal. Pre-order traversal visits children before root. For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is: 1. `1` 2. `2` 3. `3` 4. `4` 5. `5` 6. `(4 5)` 7. `6` 8. `7` 9. `8` 10. `(7 8)` 11. `(2 3 (4 5) 6 (7 8))` 12. `9` 13. `(1 (2 3 (4 5) 6 (7 8)) 9)` 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 either - nil to indicate no changes - or a valid zipper WARNING: when function `f` changes the location in the zipper, normal traversal will be affected. When `p?` is not specified `f` is called on 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 ...)) ``` See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(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)
(prepend-newline zloc n)
DEPRECATED: renamed to insert-newline-left
.
DEPRECATED: renamed to [[insert-newline-left]].
(prepend-space zloc)
(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
. If already at root, returns nil.
Return zipper with location moved to the previous depth-first non-whitespace/non-comment node in `zloc`. If already at root, returns nil.
(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.
Pre-order traversal visits root before children.
For example, traversal order of (1 (2 3 (4 5) 6 (7 8)) 9)
is:
(1 (2 3 (4 5) 6 (7 8)) 9)
1
(2 3 (4 5) 6 (7 8))
2
3
(4 5)
4
5
6
(7 8)
7
8
9
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 either
f
changes the location in the zipper, normal traversal will be affected.When p?
is not specified f
is called on 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 ...))
See docs on sub editing.
Return zipper modified by an isolated depth-first pre-order traversal. Pre-order traversal visits root before children. For example, traversal order of `(1 (2 3 (4 5) 6 (7 8)) 9)` is: 1. `(1 (2 3 (4 5) 6 (7 8)) 9)` 2. `1` 3. `(2 3 (4 5) 6 (7 8))` 4. `2` 5. `3` 6. `(4 5)` 7. `4` 8. `5` 9. `6` 10. `(7 8)` 11. `7` 12. `8` 13. `9` 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 either - nil to indicate no changes - or a valid zipper WARNING: when function `f` changes the location in the zipper, normal traversal will be affected. When `p?` is not specified `f` is called on 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 ...)) ``` See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(print zloc)
(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)
(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 zloc
with current node 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 a rightmost sibling, both leading and trailing whitespace is removed, otherwise only trailing whitespace is removed.
The result is that a following element (no matter whether it is on the same line or not) will end up at same positon (line/column) as the removed one. If a comment lies betwen the original node and the neighbour this will not hold true.
If the removed node is at end of input and is trailed by 1 or more newlines, a single trailing newline will be preserved.
Return `zloc` with current node 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 a rightmost sibling, both leading and trailing whitespace is removed, otherwise only trailing whitespace is removed. The result is that a following element (no matter whether it is on the same line or not) will end up at same positon (line/column) as the removed one. If a comment lies betwen the original node and the neighbour this will not hold true. If the removed node is at end of input and is trailed by 1 or more newlines, a single trailing newline will be preserved.
(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.
Specifically: will trim all whitespace - or whitespace up to first linebreak if present.
Same as [[remove]] but preserves newlines. Specifically: will trim all whitespace - or whitespace up to first linebreak if present.
(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 sibling of current node in zloc
.
Return zipper with location moved right to next non-whitespace/non-comment sibling of current 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 sibling of current node in zloc
.
Return zipper with location moved to the rightmost non-whitespace/non-comment sibling of current 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 sibling node in zloc
.
Return true if at rightmost non-whitespace/non-comment sibling node in `zloc`.
(root zloc)
Zips all the way up zloc
and returns the root node, reflecting any changes.
Zips all the way up `zloc` and returns 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-user-guide.adoc#sexpr-nuances).
(sexpr-able? zloc)
Return true if current node in zloc
can be sexpr
-ed.
Return true if current node in `zloc` can be [[sexpr]]-ed.
(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-clj.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-clj.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.
See docs on sub editing.
Like `->`, threads `zloc`, as an isolated sub-tree through forms, then zips up to, and locates at, the root of the modified sub-tree. See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(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.
See docs on sub editing.
Like `->`. Threads `zloc`, as an isolated sub-tree through forms, then zips up to, and locates at, the root of the modified sub-tree. See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(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.
See docs on sub editing.
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. See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(subzip zloc)
Create and return a zipper whose root is the current node in zloc
.
See docs on sub editing.
Create and return a zipper whose root is the current node in `zloc`. See [docs on sub editing](/doc/01-user-guide.adoc#sub-editing).
(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 parent of current node in zloc
, or nil
if at the top.
Return zipper with location moved up to next non-whitespace/non-comment parent of current node in `zloc`, or `nil` if at the top.
(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