@spec add_code(Sourceror.Zipper.t(), String.t() | Macro.t(), :after | :before) ::
  Sourceror.Zipper.t()

Adds the provided code to the zipper.

Use placement to determine if the code goes :after or :before the current node.

Example:

existing_zipper = """
IO.inspect("Hello, world!")
"""
|> Sourceror.parse_string!()
|> Sourceror.Zipper.zip()

new_code = """
IO.inspect("Goodbye, world!")
"""

existing_zipper
|> Igniter.Common.add_code(new_code)
|> Sourceror.Zipper.root()
|> Sourceror.to_string()

Which will produce

"""
IO.inspect("Hello, world!")
IO.inspect("Goodbye, world!")
"""

Expands the environment at the current zipper position and returns the expanded environment. Currently used for properly working with aliases.

@spec expand_literal(Sourceror.Zipper.t()) :: {:ok, any()} | :error

Expands a literal value using the env at the cursor, if possible

@spec maybe_move_to_block(Sourceror.Zipper.t()) :: Sourceror.Zipper.t()

Enters a block, and moves to the first child, or returns the zipper unmodified.

@spec maybe_move_to_single_child_block(Sourceror.Zipper.t()) :: Sourceror.Zipper.t()

Enters a block with a single child, and moves to that child, or returns the zipper unmodified

@spec move_next(Sourceror.Zipper.t(), (Sourceror.Zipper.t() -> boolean())) ::
  {:ok, Sourceror.Zipper.t()} | :error

Moves nextwards (depth-first), until the provided predicate returns true.

Returns :error if the end is reached without finding a match.

@spec move_right(Sourceror.Zipper.t(), (Sourceror.Zipper.t() -> boolean())) ::
  {:ok, Sourceror.Zipper.t()} | :error

Moves rightwards, entering blocks (and exiting them if no match is found), until the provided predicate returns true.

Returns :error if the end is reached without finding a match.

@spec move_to(Sourceror.Zipper.t(), (Sourceror.Zipper.t() -> boolean())) ::
  {:ok, Sourceror.Zipper.t()} | :error

@spec move_to(Sourceror.Zipper.t(), (Sourceror.Zipper.t() -> boolean())) ::
  {:ok, Sourceror.Zipper.t()} | :error

Moves to the next node that matches the predicate.

@spec move_to_cursor(Sourceror.Zipper.t(), Sourceror.Zipper.t() | String.t()) ::
  {:ok, Sourceror.Zipper.t()} | :error

Matches and moves to the location of a __cursor__ in provided source code.

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
|> Igniter.Code.Common.move_to_cursor(pattern)
|> Zipper.node()
# => 10

@spec move_to_cursor_match_in_scope(Sourceror.Zipper.t(), String.t() | [String.t()]) ::
  {:ok, Sourceror.Zipper.t()} | :error

Moves to the cursor that matches the provided pattern or one of the provided patterns, in the current scope.

See move_to_cursor/2 for an example of a pattern

@spec move_to_do_block(Sourceror.Zipper.t()) :: {:ok, Sourceror.Zipper.t()} | :error

Moves to a do block for the current call.

For example, at a node like:

foo do
  10
end

You would get a zipper back at 10.

Moves to the next node that matches the given pattern.

Moves to the next zipper that matches the predicate.

Returns true if the current node matches the given pattern.

Examples:

list_zipper =
  "[1, 2, 3]"
  |> Sourceror.parse_string!()
  |> Sourceror.Zipper.zip()

Common.node_matches_pattern?(list_zipper, value when is_list(value)) # true

@spec nth_right(Sourceror.Zipper.t(), non_neg_integer()) ::
  {:ok, Sourceror.Zipper.t()} | :error

Moves the zipper right n times, returning :error if it can't move that many times.

@spec remove(Sourceror.Zipper.t(), (Sourceror.Zipper.t() -> boolean())) ::
  Sourceror.Zipper.t()

Removes any nodes matching the provided pattern, until there are no matches left.

@spec rightmost(Sourceror.Zipper.t()) :: Sourceror.Zipper.t()

Moves the zipper all the way to the right, potentially entering a single value block.

@spec update_all_matches(
  Sourceror.Zipper.t(),
  (Sourceror.Zipper.t() -> boolean()),
  (Sourceror.Zipper.t() ->
     {:ok, Sourceror.Zipper.t() | {:code, term()}} | {:warning | :error, term()})
) :: {:ok, Sourceror.Zipper.t()} | {:warning | :error, term()}

Updates all nodes matching the given predicate with the given function.

Recurses until the predicate no longer returns false

Replaces full module names in new_code with any aliases for that module found in the current_code environment.

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

fun must return {:ok, zipper} or :error, which may be positioned at the top of the subtree.