@spec add_issue(t(), Recode.Issue.t()) :: t()

Adds the given issue to the source.

@spec add_issues(t(), [Recode.Issue.t()]) :: t()

Adds the given issues to the source.

@spec ast(t()) :: {:ok, Macro.t()} | {:error, term()}

Returns the AST for the given %Source.

The returned extended AST is generated with Sourceror.parse_string/1.

Uses the current code of the source.

examples

Examples

iex> "def foo, do: :foo" |> Source.from_string() |> Source.ast()
{:def, [trailing_comments: [], leading_comments: [], line: 1, column: 1],
  [
    {:foo, [trailing_comments: [], leading_comments: [], line: 1, column: 5], nil},
    [
      {{:__block__,
        [trailing_comments: [], leading_comments: [], format: :keyword, line: 1, column: 10],
        [:do]},
       {:__block__, [trailing_comments: [], leading_comments: [], line: 1, column: 14], [:foo]}}
    ]
  ]
}

@spec code(t()) :: String.t()

Returns the current code for the given source.

@spec code(t(), version()) :: String.t()

Returns the code of a source for the given version.

examples

Examples

iex> bar =
...>   """
...>   defmodule Bar do
...>      def bar, do: :bar
...>   end
...>   """
iex> foo =
...>   """
...>   defmodule Foo do
...>      def foo, do: :foo
...>   end
...>   """
iex> source = Source.from_string(bar)
iex> source = Source.update(source, :example, code: foo)
iex> Source.code(source) == foo
true
iex> Source.code(source, 2) == foo
true
iex> Source.code(source, 1) == bar
true

@spec compare(t(), t()) :: :lt | :eq | :gt

Compares the path values of the given sources.

examples

Examples

iex> a = Source.from_string(":foo", "a.exs")
iex> Source.compare(a, a)
:eq
iex> b = Source.from_string(":foo", "b.exs")
iex> Source.compare(a, b)
:lt
iex> Source.compare(b, a)
:gt

@spec debug_info!(t(), module()) :: term()

Same as debug_info/1 but raises on error.

@spec debug_info(t(), module()) :: {:ok, term()} | {:error, term()}

Returns the debug info for the give source and module.

Uses the current code of the source.

examples

Examples

iex> bar =
...>   """
...>   defmodule Bar do
...>      def bar, do: :bar
...>   end
...>   """
iex> bar |> Source.from_string() |> Source.debug_info(Bar)
{:ok,
 %{
   attributes: [],
   compile_opts: [],
   definitions: [{{:bar, 0}, :def, [line: 2], [{[line: 2], [], [], :bar}]}],
   deprecated: [],
   file: "nofile",
   is_behaviour: false,
   line: 1,
   module: Bar,
   relative_file: "nofile",
   struct: nil,
   unreachable: []
 }}

@spec del(t(), nil | module()) :: t()

Marks the given source as deleted.

This function set the path of the given source to nil.

@spec from_string(String.t(), Path.t() | nil) :: t()

Creates a new %Source{} from the given string.

examples

Examples

iex> source = Source.from_string("a + b")
iex> source.modules
[]
iex> source.code
"a + b"

@spec has_issues?(t(), version() | :actual | :all) :: boolean()

Returns true if the source has issues for the given version.

The version argument also accepts :actual and :all to check whether the source has problems for the actual version or if there are problems at all.

examples

Examples

iex> alias Recode.Issue
iex> source =
...>   "a + b"
...>   |> Source.from_string("some/where/plus.exs")
...>   |> Source.add_issue(Issue.new(:test, "no comment", line: 1))
...>   |> Source.update(:example, path: "some/where/else/plus.exs")
...>   |> Source.add_issue(Issue.new(:test, "no comment", line: 1))
iex> Source.has_issues?(source)
true
iex> Source.has_issues?(source, 1)
true
iex> Source.has_issues?(source, :all)
true
iex> source = Source.update(source, :example, code: "a - b")
iex> Source.has_issues?(source)
false
iex> Source.has_issues?(source, 2)
true
iex> Source.has_issues?(source, :all)
true

@spec modules(t()) :: [module()]

Returns the current modules for the given source.

@spec modules(t(), version()) :: [module()]

Returns the modules of a source for the given version.

examples

Examples

iex> bar =
...>   """
...>   defmodule Bar do
...>      def bar, do: :bar
...>   end
...>   """
iex> foo =
...>   """
...>   defmodule Foo do
...>      def foo, do: :foo
...>   end
...>   """
iex> source = Source.from_string(bar)
iex> source = Source.update(source, :example, code: bar <> foo)
iex> Source.modules(source)
[Bar, Foo]
iex> Source.modules(source, 2)
[Bar, Foo]
iex> Source.modules(source, 1)
[Bar]

@spec new!(Path.t()) :: t()

Creates a new %Source{} from the given path.

examples

Examples

iex> source = Source.new!("test/fixtures/source/simple.ex")
iex> source.modules
[MyApp.Simple]
iex> source.code
"""
defmodule MyApp.Simple do
  def foo(x) do
    x * 2
  end
end
"""

@spec path(t()) :: Path.t() | nil

Returns the current path for the given source.

@spec path(t(), version()) :: Path.t() | nil

Returns the path of a source for the given version.

examples

Examples

iex> source =
...>   "a + b"
...>   |> Source.from_string("some/where/plus.exs")
...>   |> Source.update(:example, path: "some/where/else/plus.exs")
...> Source.path(source, 1)
"some/where/plus.exs"
iex> Source.path(source, 2)
"some/where/else/plus.exs"

@spec save(t()) :: :ok | {:error, :nofile | File.posix()}

Saves the source to disk.

If the source :path was updated then the old file will be deleted. The original file will also deleted when the source was marked as deleted with del/1.

Missing directories are created.

examples

Examples

iex> ":test" |> Source.from_string() |> Source.save()
{:error, :nofile}

iex> path = "tmp/foo.ex"
iex> File.write(path, ":foo")
iex> source = path |> Source.new!() |> Source.update(:test, code: ":bar")
iex> Source.save(source)
:ok
iex> File.read(path)
{:ok, ":bar\n"}
iex> source |> Source.del() |> Source.save()
iex> File.exists?(path)
false

iex> source = Source.from_string(":bar")
iex> Source.save(source)
{:error, :nofile}
iex> source |> Source.update(:test, path: "tmp/bar.ex") |> Source.save()
:ok

iex> path = "tmp/ping.ex"
iex> File.write(path, ":ping")
iex> source = path |> Source.new!()
iex> new_path = "tmp/pong.ex"
iex> source |> Source.update(:test, path: new_path) |> Source.save()
:ok
iex> File.exists?(path)
false
iex> File.read(new_path)
{:ok, ":ping"}

@spec update(
  t(),
  by(),
  [{:code, String.t() | Sourceror.Zipper.zipper()}] | [{:path, Path.t()}]
) :: t()

Updates the code or the path of a source.

examples

Examples

iex> source =
...>   "a + b"
...>   |> Source.from_string()
...>   |> Source.update(:example, path: "test/fixtures/new.exs")
...>   |> Source.update(:example, code: "a - b")
iex> source.updates
[{:code, :example, "a + b"}, {:path, :example, nil}]
iex> source.code
"a - b\n"

If the new value equal to the current value, no updates will be added.

iex> source =
...>   "a = 42"
...>   |> Source.from_string()
...>   |> Source.update(:example, code: "b = 21")
...>   |> Source.update(:example, code: "b = 21")
...>   |> Source.update(:example, code: "b = 21")
iex> source.updates
[{:code, :example, "a = 42"}]

@spec updated?(t(), kind :: :code | :path | :any) :: boolean()

Returns true if the source was updated.

The optional argument kind specifies whether only :code changes or :path changes are considered. Defaults to :any.

examples

Examples

iex> source = Source.from_string("a = 42")
iex> Source.updated?(source)
false
iex> source = Source.update(source, :example, code: "b = 21")
iex> Source.updated?(source)
true
iex> Source.updated?(source, :path)
false
iex> Source.updated?(source, :code)
true

@spec version(t()) :: version()

Returns the version of the given source. The value 1 indicates that the source has no changes.

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

Returns a Sourceror.Zipper with the AST for the given %Source.