Inserts the child as the rightmost child of the node at this zipper, without moving.

@spec at(Macro.t(), Sourceror.position()) :: {:ok, t()} | :error

Creates a zipper from a tree node focused at the innermost descendant containing position.

Returns {:ok, zipper} if position is within node, else :error.

Modifying node prior to using at/2 is not recommended as added or changed descendants may not contain accurate position metadata used to find the focus.

@spec children(tree()) :: [tree()] | nil

Returns a list of children of the node. Returns nil if the node is a leaf.

@spec down(t()) :: t() | nil

@spec down(nil) :: nil

Returns the zipper of the leftmost child of the node at this zipper, or nil if there's no children.

If passed nil, this function returns nil.

@spec find(t(), direction :: :prev | :next, predicate :: (tree() -> any())) ::
  t() | nil

@spec find(nil, direction :: :prev | :next, predicate :: (tree() -> any())) :: nil

Returns a zipper to the node that satisfies the predicate function, or nil if none is found.

The optional second parameters specifies the direction, defaults to :next.

If passed nil, this function returns nil.

@spec find_all(t(), direction :: :prev | :next, predicate :: (tree() -> any())) :: [
  t()
]

@spec find_all(nil, direction :: :prev | :next, predicate :: (tree() -> any())) :: []

Returns a list of zippers to each node that satisfies the predicate function, or an empty list if none are found.

The optional second parameters specifies the direction, defaults to :next.

If passed nil, this function returns the empty list.

Like find/3, but returns the first non-falsy value returned by fun.

If passed nil, this function returns nil.

Inserts the child as the leftmost child of the node at this zipper, without moving.

@spec insert_left(t(), tree()) :: t()

Inserts the child as the left sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

@spec insert_right(t(), tree()) :: t()

Inserts the child as the right sibling of the node at this zipper, without moving. Raises an ArgumentError when attempting to insert a sibling at the top level.

@spec left(t()) :: t() | nil

@spec left(nil) :: nil

Returns the zipper of the left sibling of the node at this zipper, or nil.

If passed nil, this function returns nil.

@spec leftmost(t()) :: t()

@spec leftmost(nil) :: nil

Returns the leftmost sibling of the node at this zipper, or itself.

If passed nil, this function returns nil.

@spec make_node(tree(), [tree()]) :: tree()

Returns a new branch node, given an existing node and new children.

@spec move_to_cursor(t(), String.t() | t()) :: t() | nil

@spec move_to_cursor(nil, String.t() | t()) :: nil

Matches zipper against the given pattern, moving to the location of __cursor__().

This function only moves zipper if the current node matches the pattern. To search for a pattern in zipper, use search_pattern/2.

There are two special forms that can be used inside patterns:

• __cursor__() - if the pattern matches, the zipper will be focused at the location of __cursor__(), if present
• __ - "wildcard match" that will match a single node of any form.

If passed nil, this function returns nil.

Examples

iex> zipper =
...>   """
...>   if true do
...>     10
...>   end
...>   """
...>   |> Sourceror.parse_string!()
...>   |> zip()
iex> pattern =
...>   """
...>   if __ do
...>     __cursor__()
...>   end
...>   """
iex> found = move_to_cursor(zipper, pattern)
iex> {:__block__, _, [10]} = found.node

@spec next(t()) :: t() | nil

@spec next(nil) :: nil

Returns the following zipper in depth-first pre-order.

If passed nil, this function returns nil.

@spec node(t()) :: tree()

Returns the node at the zipper.

@spec prev(t()) :: t()

Returns the previous zipper in depth-first pre-order. If it's already at the end, it returns nil.

@spec remove(t()) :: t()

Removes the node at the zipper, returning the zipper that would have preceded it in a depth-first walk. Raises an ArgumentError when attempting to remove the top level node.

@spec replace(t(), tree()) :: t()

Replaces the current node in the zipper with a new node.

@spec right(t()) :: t() | nil

@spec right(nil) :: nil

Returns the zipper of the right sibling of the node at this zipper, or nil.

If passed nil, this function returns nil.

@spec rightmost(t()) :: t()

@spec rightmost(nil) :: nil

Returns the rightmost sibling of the node at this zipper, or itself.

If passed nil, this function returns nil.

@spec root(t()) :: tree()

Walks the zipper to the top of the current subtree and returns the that node.

@spec search_pattern(t(), String.t() | t()) :: t() | nil

@spec search_pattern(nil, String.t() | t()) :: nil

Searches forward in zipper for the given pattern, moving to that pattern or a location inside that pattern.

Note that the search may continue outside of zipper in a depth-first order. If this isn't desirable, call this function with a subtree/1.

If passed nil, this function returns nil.

There are two special forms that can be used inside patterns:

• __cursor__() - if the pattern matches, the zipper will be focused at the location of __cursor__(), if present
• __ - "wildcard match" that will match a single node of any form.

Examples

iex> zipper =
...>   """
...>   defmodule Example do
...>     def my_function(arg1, arg2) do
...>       arg1 + arg2
...>     end
...>   end
...>   """
...>   |> Sourceror.parse_string!()
...>   |> zip()
...> found = search_pattern(zipper, "my_function(arg1, arg2)")
...> {:my_function, _, [{:arg1, _, _}, {:arg2, _, _}]} = found.node
...> found = search_pattern(zipper, "my_function(__, __)")
...> {:my_function, _, [{:arg1, _, _}, {:arg2, _, _}]} = found.node
...> found = search_pattern(zipper, "def my_function(__, __cursor__()), __")
...> {:arg2, _, _} = found.node

@spec skip(t(), direction :: :next | :prev) :: t() | nil

@spec skip(nil, direction :: :next | :prev) :: nil

Returns the zipper of the right sibling of the node at this zipper, or the next zipper when no right sibling is available.

This allows to skip subtrees while traversing the siblings of a node.

The optional second parameters specifies the direction, defaults to :next.

If no right/left sibling is available, this function returns the same value as next/1/prev/1.

The function skip/1 behaves like the :skip in traverse_while/2 and traverse_while/3.

If passed nil, this function returns nil.

@spec subtree(t()) :: t()

Returns a new zipper that is a subtree of the currently focused node.

@spec supertree(t()) :: t() | nil

Moves to the top and breaks out of a subtree.

Returns nil if zipper is not a subtree.

@spec top(t()) :: t()

Walks the zipper to the top of the current subtree and returns that zipper.

@spec topmost(t()) :: t()

Walks the zipper to the topmost node, breaking out of any subtrees and returns the top-most zipper.

@spec topmost_root(t()) :: tree()

Walks the zipper to the topmost node, breaking out of any subtrees and returns the root node.

@spec traverse(t(), (t() -> t())) :: t()

Traverses the tree in depth-first pre-order calling the given fun for each node. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

The function must return a zipper.

@spec traverse(t(), term(), (t(), term() -> {t(), term()})) :: {t(), term()}

Traverses the tree in depth-first pre-order calling the given fun for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

@spec traverse_while(t(), (t() -> {:cont, t()} | {:halt, t()} | {:skip, t()})) :: t()

Traverses the tree in depth-first pre-order calling the given fun for each node.

The traversing will continue if fun returns {:cont, zipper}, skipped for {:skip, zipper} and halted for {:halt, zipper}. When the traversal is finished, the zipper will be back where it began.

If the zipper is not at the top, just the subtree will be traversed.

The function must return a zipper.

@spec traverse_while(
  t(),
  term(),
  (t(), term() ->
     {:cont, t(), term()} | {:halt, t(), term()} | {:skip, t(), term()})
) :: {t(), term()}

Traverses the tree in depth-first pre-order calling the given fun for each node with an accumulator. When the traversal is finished, the zipper will be back where it began.

The traversing will continue if fun returns {:cont, zipper, acc}, skipped for {:skip, zipper, acc} and halted for {:halt, zipper, acc}

If the zipper is not at the top, just the subtree will be traversed.

@spec up(t()) :: t() | nil

Returns the zipper for the parent node of the given zipper, or nil if the zipper points to the root.

@spec update(t(), (tree() -> tree())) :: t()

Replaces the current node in the zipper with the result of applying fun to the node.

Runs the function fun on the subtree of the currently focused node and returns the updated zipper.

fun must return a zipper, which may be positioned at the top of the subtree.

@spec zip(tree()) :: t()

Creates a zipper from a tree node.