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

Adds the provided code to the zipper.

Options

• :placement - :after | :before. Determines if the code goes :after or :before the current node. Defaults to :after.

@spec find_all(Sourceror.Zipper.t(), predicate :: (Sourceror.Zipper.t() -> boolean())) ::
  [
    Sourceror.Zipper.t()
  ]

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.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> zippers = Sourceror.Code.Common.find_all(zipper, fn z -> match?({:__block__, _, [_]}, z.node) end)
iex> length(zippers) >= 3
true

See also move_to/2.

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

Examples

iex> zipper = Sourceror.parse_string!("(1 + 2)") |> Sourceror.Zipper.zip()
iex> zipper = Sourceror.Code.Common.maybe_move_to_block(zipper)
iex> match?({:+, _, _}, zipper.node)
true

See also maybe_move_to_single_child_block/1.

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

Examples

iex> zipper = Sourceror.parse_string!("(1)") |> Sourceror.Zipper.zip()
iex> zipper = Sourceror.Code.Common.maybe_move_to_single_child_block(zipper)
iex> match?({:__block__, _, [1]}, zipper.node)
true

See also maybe_move_to_block/1.

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

Moves a zipper to the left.

If the second argument is a predicate function, it will be called on the zipper and then move leftwards until the predicate returns true. This function will automatically enter and exit blocks.

If the second argument is a non-negative integer, it will move left that many times if possible, returning :error otherwise.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Common.move_to(zipper, fn z -> match?({:__block__, _, [3]}, z.node) end)
iex> {:ok, zipper} = Sourceror.Code.Common.move_left(zipper, 1)
iex> match?({:__block__, _, [2]}, zipper.node)
true

See also move_right/2.

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

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> {:ok, result} = Sourceror.Code.Common.move_next(zipper, fn z -> match?({:__block__, _, [2]}, z.node) end)
iex> match?({:__block__, _, [2]}, result.node)
true

See also move_to/2.

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

Moves a zipper to the right.

If the second argument is a predicate function, it will be called on the zipper and then move rightwards until the predicate returns true. This function will automatically enter and exit blocks.

If the second argument is a non-negative integer, it will move right that many times if possible, returning :error otherwise.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Common.move_to(zipper, fn z -> match?({:__block__, _, [1]}, z.node) end)
iex> {:ok, zipper} = Sourceror.Code.Common.move_right(zipper, 1)
iex> match?({:__block__, _, [2]}, zipper.node)
true

See also move_left/2.

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

Moves to the first node that matches the predicate.

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> {:ok, result} = Sourceror.Code.Common.move_to(zipper, fn z -> match?({:=, _, _}, z.node) end)
iex> match?({:=, _, _}, result.node)
true

See also move_to_last/2.

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

See also move_upwards/2.

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

Moves to the last node that matches the predicate.

Similar to move_to/2 but it doesn't stop at the first match, for example a zipper for the following code:

port = 4000
port = 4001

With a match for port = _ as {:=, _, [{:port, _, _}, _]}, will return the second port variable.

Moves to the next node that matches the given pattern.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> {:ok, result} = Sourceror.Code.Common.move_to_pattern(zipper, {:__block__, _, [2]})
iex> match?({:__block__, _, [2]}, result.node)
true

See also node_matches_pattern?/2.

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

Moves to the next zipper that matches the predicate.

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> {:ok, result} = Sourceror.Code.Common.move_to_zipper(zipper, fn z -> match?({:=, _, _}, z.node) end)
iex> match?({:=, _, _}, result.node)
true

See also move_to/2.

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

Moves a zipper upwards.

If the second argument is a predicate function, it will be called on the zipper and then move upwards until the predicate returns true.

If the second argument is a non-negative integer, it will move upwards that many times if possible, returning :error otherwise.

Examples

iex> zipper = Sourceror.parse_string!("defmodule Foo do\ndef bar do\n1\nend\nend") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Function.move_to_def(zipper, :bar, 0)
iex> {:ok, zipper} = Sourceror.Code.Common.move_upwards(zipper, &match?({:defmodule, _, _}, &1.node))
iex> match?({:defmodule, _, _}, zipper.node)
true

See also move_upwards_until/2.

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

Moves to the last node before the node that matches the predicate, going upwards.

Examples

iex> zipper = Sourceror.parse_string!("defmodule Foo do\ndef bar do\n1\nend\nend") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Function.move_to_def(zipper, :bar, 0)
iex> {:ok, zipper} = Sourceror.Code.Common.move_upwards_until(zipper, &match?({:defmodule, _, _}, &1.node))
iex> match?({:defmodule, _, _}, zipper.node)
true

See also move_upwards/2.

Returns true if the current node matches the given pattern.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> Sourceror.Code.Common.node_matches_pattern?(zipper, value when is_list(value))
true

See also move_to_pattern/2.

@spec nodes_equal?(Sourceror.Zipper.t() | Macro.t(), Macro.t()) :: boolean()

Checks if two nodes are equal.

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> node = Sourceror.Zipper.node(zipper)
iex> Sourceror.Code.Common.nodes_equal?(zipper, node)
true

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

See also remove_all_matches/2.

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

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

Recurses until the predicate no longer returns false.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> zipper = Sourceror.Code.Common.remove_all_matches(zipper, 
...>   fn z -> match?({:__block__, _, [2]}, z.node) end)
iex> Sourceror.to_string(zipper.node)
"[1, 3]"

See also update_all_matches/3.

Replaces code with new code.

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> zipper = Sourceror.Code.Common.move_to_zipper(zipper, fn z -> match?({:=, _, _}, z.node) end) |> elem(1)
iex> zipper = Sourceror.Code.Common.replace_code(zipper, "bar = 2")
iex> Sourceror.to_string(zipper.node)
"bar = 2"

See also add_code/3.

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

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Common.update_all_matches(zipper, 
...>   fn z -> match?({:=, _, _}, z.node) end,
...>   fn z -> {:ok, Sourceror.Code.Common.replace_code(z, "bar = 2")} end)
iex> Sourceror.to_string(zipper.node) |> String.contains?("bar = 2")
true

See also remove_all_matches/2.

@spec variable_assignment?(zipper :: Sourceror.Zipper.t(), name :: atom()) ::
  boolean()

Returns true if the node represents a variable assignment.

Examples

iex> zipper = Sourceror.parse_string!("foo = 1") |> Sourceror.Zipper.zip()
iex> Sourceror.Code.Common.variable_assignment?(zipper, :foo)
true
iex> Sourceror.Code.Common.variable_assignment?(zipper, :bar)
false

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.

Examples

iex> zipper = Sourceror.parse_string!("[1, 2, 3]") |> Sourceror.Zipper.zip()
iex> {:ok, zipper} = Sourceror.Code.Common.within(zipper, fn z -> 
...>   {:ok, Sourceror.Code.Common.replace_code(z, "[4, 5, 6]")}
...> end)
iex> Sourceror.to_string(zipper.node)
"[4, 5, 6]"