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

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

@spec find(t(), direction :: :prev | :next, predicate :: (tree() -> any())) ::
  t() | 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.

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

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

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

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

@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

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

Use __cursor__() to match a cursor in the provided source code. Use __ to skip any code at a point.

For example:

zipper =
  """
  if true do
    10
  end
  """
  |> Sourceror.Zipper.zip()

pattern =
  """
  if __ do
    __cursor__()
  end
  """

zipper
|> Zipper.move_to_cursor(pattern)
|> Zipper.node()
# => 10

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

@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

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

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

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

@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

Searches zipper for the given pattern, moving to that pattern or to the location of __cursor__() in that pattern.

@spec skip(t(), direction :: :next | :prev) :: t() | 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.

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

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

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