Rewrite

https://hexdocs.pm/rewrite/
Admin
Rewrite is a tool for modifying, adding, and removing files within a Mix project, designed for use...
Tokens:29,098
Snippets:104
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Source File Reading Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates creating a Source struct by reading content from a file using the `read!/1` function, displaying the loaded content.

```elixir
iex> source = Source.read!("test/fixtures/source/hello.txt")
iex> source.content
"hello\n"
```

--------------------------------

### Rewrite.Source.Ex API Documentation

Source: https://hexdocs.pm/rewrite/Rewrite.Source.Ex

Provides documentation for the functions within the Rewrite.Source.Ex module, including their signatures, parameters, return values, and usage examples.

```APIDOC
Rewrite.Source.Ex Functions:

format(source, formatter_opts \ nil)
  Deprecated: This function is deprecated. Use the formatting functionality provided by Rewrite.DotFormatter instead.

from_string(string, opts \ [])
  Returns a %Rewrite.Source{} with an added :filetype.
  Parameters:
    string: The Elixir code as a string.
    opts: Keyword list of options.
  Returns: A %Rewrite.Source{} struct.
  Example:
    iex> source = Source.Ex.from_string("Enum.reverse(list)")

modules(source)
  Returns the current modules for the given `source`.
  Parameters:
    source: A %Rewrite.Source{} struct.
  Returns: A list of modules.
  Example:
    iex> bar = "defmodule Bar do\n   def bar, do: :bar\nend"
    iex> foo = "defmodule Baz.Foo do\n   def foo, do: :foo\nend"
    iex> source = Source.update(source, :content, bar <> foo)
    iex> Source.Ex.modules(source)
    [Baz.Foo, Bar]

modules(source, version)
  Returns the modules of a `source` for the given `version`.
  Parameters:
    source: A %Rewrite.Source{} struct.
    version: The version number.
  Returns: A list of modules.
  Example:
    iex> Source.Ex.modules(source, 2)
    [Baz.Foo, Bar]
    iex> Source.Ex.modules(source, 1)
    [Bar]

put_formatter_opts(source, opts)
  Deprecated: This function is deprecated. Use the formatting functionality provided by Rewrite.DotFormatter instead.

read!(path, opts \ [])
  Returns a %Rewrite.Source{} with an added :filetype.
  The content reads from the file under the given path.
  Parameters:
    path: The file path.
    opts: Keyword list of options.
      :resync_quoted, default: `true` - forcing the re-parsing when the source field `quoted` is updated.
  Returns: A %Rewrite.Source{} struct.
  Example:
    iex> project = Rewrite.new(filetypes: [{Source.Ex, resync_quoted: false}])
    iex> path = "test/fixtures/source/simple.ex"
    iex> project = Rewrite.read!(project, path)
    iex> source = Rewrite.source!(project, path)

```

--------------------------------

### Source Manipulation and Undo Examples

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates basic usage of Source.from_string, Source.update, and Source.undo for managing source content and paths, including multi-step undo operations.

```elixir
iex> a = Source.from_string("test-a", path: "test/foo.txt")
iex> b = Source.update(a, :content, "test-b")
iex> c = Source.update(b, :path, "test/bar.txt")
iex> d = Source.update(c, :content, "test-d")
iex> d |> Source.undo() |> Source.get(:content)
"test-b"
iex> d |> Source.undo(1) |> Source.get(:content)
"test-b"
iex> d |> Source.undo(2) |> Source.get(:path)
"test/foo.txt"
iex> d |> Source.undo(3) |> Source.get(:content)
"test-a"
iex> d |> Source.undo(9) |> Source.get(:content)
"test-a"
iex> d |> Source.undo(9) |> Source.updated?()
false
iex> d |> Source.undo(-9) |> Source.get(:content)
"test-d"
```

--------------------------------

### Source Creation from String Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates how to create a Source struct from a string using the `from_string/2` function, showing default nil values and how to provide options like path and owner.

```elixir
iex> source = Source.from_string("hello")
iex> source.content
"hello"
iex> source.path
nil
iex> source.owner
Rewrite

iex> source = Source.from_string("hello", path: "hello.md", owner: MyApp)
iex> source.path
"hello.md"
iex> source.owner
MyApp
```

--------------------------------

### Source Data Retrieval Examples

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Illustrates retrieving content and path from a Source struct, including version-specific retrieval and updating content, demonstrating the `get/2`, `get/3`, and `update/3` functions.

```elixir
iex> bar = "defmodule Bar do\n   def bar, do: :bar\nend"
iex> foo = "defmodule Foo do\n   def foo, do: :foo\nend"
iex> source = Source.Ex.from_string(bar)
iex> source = Source.update(source, :content, foo)
iex> Source.get(source, :content) == foo
true
iex> Source.get(source, :content, 2) == foo
true
iex> Source.get(source, :content, 1) == bar
true

iex> source = "hello" |> Source.from_string(path: "some/where/hello.txt") |> Source.update(:path, "some/where/else/hello.txt")
iex> Source.get(source, :path, 1)
"some/where/hello.txt"
iex> Source.get(source, :path, 2)
"some/where/else/hello.txt"
```

--------------------------------

### Elixir Source Origin Check Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Shows how to use the `Source.from?/2` function to determine if a Source struct was created from a file or a string.

```elixir
source = Source.from_string("hello")
Source.from?(source, :file)
Source.from?(source, :string)

```

--------------------------------

### Elixir Code Formatting Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates how to format Elixir code strings using `Code.format_string!/1` and then apply it to a Source struct. It also shows how to generate a diff between the original and formatted code.

```elixir
code = """
def foo( x ) do
  {:x,
    x}
end
"""
formatted = code |> Code.format_string!() |> IO.iodata_to_binary()
source = Source.Ex.from_string(code)
source |> Source.diff() |> IO.iodata_to_binary()

source
|> Source.update(:content, formatted)
|> Source.diff(color: false)
|> IO.iodata_to_binary()

```

--------------------------------

### Elixir Source Formatting Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates formatting an Elixir Source struct with specific options. It shows how to use `Source.format/2` with `force_do_end_blocks: true` and how to provide a custom `dot_formatter` to control formatting details like `locals_without_parens`.

```elixir
source = Source.Ex.from_string("""
defmodule    Foo do
    def   foo(x),   do:    bar x
   end
""")

{:ok, formatted} = Source.format(source, force_do_end_blocks: true)
formatted.content

dot_formatter = DotFormatter.from_formatter_opts(locals_without_parens: [bar: 1])
{:ok, formatted} = Source.format(source,
  dot_formatter: dot_formatter, force_do_end_blocks: true
)
formatted.content

```

--------------------------------

### Source Issue Tracking Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates how to add issues to a Source struct and check for their existence using `add_issue/2` and `has_issues?/2`. Shows checking issues for the actual version, all versions, and specific versions.

```elixir
iex> source = "a + b" |> Source.Ex.from_string(path: "some/where/plus.exs") |> Source.add_issue(%{issue: :foo}) |> Source.update(:path, "some/where/else/plus.exs") |> Source.add_issue(%{issue: :bar})
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, :content, "a - b")
iex> Source.has_issues?(source)
false
iex> Source.has_issues?(source, 2)
true
iex> Source.has_issues?(source, :all)
true
```

--------------------------------

### Formatter Retrieval and Options

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Functions to retrieve a formatter function for a given file, get formatter options, and create DotFormatter structs from options. Includes functions to get specific formatter options for a file and to retrieve the DotFormatter struct by path.

```APIDOC
formatter_for_file(dot_formatter, file, opts \ [])
  @spec formatter_for_file(t(), Path.t(), keyword()) :: formatter()
  Returns a formatter function to be used for the given file. The returned function takes a string or an Elixir AST and returns the formatted string. The option :from takes the value :string or :quoted to determine which input type is used by the formatter, defaulting to :string. The function also accepts the same options as Code.format_string!/2, these are used when the formatter is called.

formatter_opts(dot_formatter)
  @spec formatter_opts(t()) :: keyword()
  Returns the formatter options for the given dot_formatter. This functions ignores the sub-formatters of the given dot_formatter.

formatter_opts_for_file(dot_formatter, file)
  @spec formatter_opts_for_file(t(), Path.t()) :: keyword()
  Returns the formatter options for the given dot_formatter and file. This fucntion searches the formatter for the given file and returns the formatter options for that formatter in an :ok tuple. If no formatter or multiple formatters are found, an :error tuple is returned.

from_formatter_opts(formatter_opts, opts \ [])
  @spec from_formatter_opts(keyword(), keyword()) :: t()
  Creates a %DotFormatter{} struct from a the given formatter_opts. This function ignores the sub-formatters of the given formatter_opts. It is also assumes that the plugins are already loaded.

get(dot_formatter, path)
  @spec get(t(), path :: Path.t()) :: t()
  Returns the %DotFormatter{} struct for the given path or nil when not found.
```

--------------------------------

### Get Specific Source by Path

Source: https://hexdocs.pm/rewrite/Rewrite

Retrieves the `%Rewrite.Source{}` struct for a given file path. Returns an {:ok, source} tuple if exactly one source matches the path, otherwise returns an {:error, reason} tuple.

```elixir
@spec source(t(), Path.t()) :: {:ok, Rewrite.Source.t()} | {:error, Rewrite.Error.t()}

Returns the `%Rewrite.Source{}` for the given `path`.

Returns an `:ok` tuple with the found source, if not exactly one source is
available an `:error` is returned.

See also `sources/2` to get a list of sources for a given `path`.
```

--------------------------------

### Get Specific Source (Raises Exception)

Source: https://hexdocs.pm/rewrite/Rewrite

Identical to `source/2`, but raises a `Rewrite.Error` exception upon failure instead of returning an error tuple. This is useful when a missing source should cause an immediate program termination.

```elixir
@spec source!(t(), Path.t()) :: Rewrite.Source.t()

Same as [`source/2`](#source/2), but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of
failure.
```

--------------------------------

### Elixir File Changed Check Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Illustrates the usage of `Source.file_changed?/1`. It shows how to read a file into a Source struct, modify the file, and check the status. It also covers cases where the source is from a string or the file is deleted.

```elixir
File.write("tmp/hello.txt", "hello")
source = Source.read!("tmp/hello.txt")
Source.file_changed?(source)

File.write("tmp/hello.txt", "Hello, world!")
Source.file_changed?(source)

source = Source.update(source, :path, nil)
Source.file_changed?(source)

File.write("tmp/hello.txt", "hello")
Source.file_changed?(source)

File.rm!("tmp/hello.txt")
Source.file_changed?(source)

source = Source.from_string("hello")
Source.file_changed?(source)

```

--------------------------------

### DotFormatter Manipulation

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Utilities for manipulating DotFormatter structs, including mapping functions over them and reducing them with an accumulator. Also includes a function to get all input globs from a DotFormatter.

```APIDOC
inputs(dot_formatter)
  @spec inputs(t()) :: [GlobEx.t()]
  Returns a list of all :inputs from the given dot_formatter and any sub-formatters.

map(dot_formatter, fun)
  @spec map(t(), (t() -> t())) :: t()
  Returns a %DotFormatter{} struct with the result of invoking fun on the given dot_formatter and any sub-formatters.

reduce(dot_formatter, acc \ [], fun)
  @spec reduce(t(), acc, (t(), acc -> acc)) :: acc when acc: term()
  Invokes fun for each dot_formatter and any sub-formatters with the accumulator.
```

--------------------------------

### has_source? - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Checks if a Rewrite project contains a source with a specific path. Returns true if found, false otherwise. Includes example usage.

```APIDOC
@spec has_source?(t(), Path.t()) :: boolean()
```

--------------------------------

### Private Data Storage Example

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Shows how to use the `put_private/3` function to store arbitrary data within the Source struct's private map, which is not accessed by the Rewrite library itself.

```elixir
iex> source = "a + b" |> Source.from_string() |> Source.put_private(:origin, :example)
iex> source.private[:origin]
:example
```

--------------------------------

### from_sources - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Creates a Rewrite project from a list of sources. It returns {:ok, rewrite} for valid sources or {:error, error} if sources have missing paths or duplicates.

```APIDOC
@spec from_sources([Rewrite.Source.t()], opts()) :: {:ok, t()} | {:error, term()}
```

--------------------------------

### List All Sources

Source: https://hexdocs.pm/rewrite/Rewrite

Returns a list of all `Rewrite.Source.t()` structs currently managed by the project, sorted by their file paths. This provides a comprehensive overview of all sources in the project.

```elixir
@spec sources(t()) :: [Rewrite.Source.t()]

Returns all sources sorted by path.
```

--------------------------------

### Put Source into Rewrite Project

Source: https://hexdocs.pm/rewrite/Rewrite

Adds a given source to the rewrite project. Returns an {:ok, rewrite} tuple on success or an {:error, reason} tuple on failure. Handles cases like overwriting existing sources or missing paths.

```elixir
@spec put(t(), Rewrite.Source.t()) :: {:ok, t()} | {:error, Rewrite.Error.t()}

Puts the given `source` to the given `rewrite` project.

Returns `{:ok, rewrite}` if successful, `{:error, reason}` otherwise.

## Examples

```elixir
iex> project = Rewrite.new()
iex> {:ok, project} = Rewrite.put(project, Source.from_string(":a", path: "a.exs"))
iex> map_size(project.sources)
1
iex> Rewrite.put(project, Source.from_string(":b"))
{:error, %Rewrite.Error{reason: :nopath}}
iex> Rewrite.put(project, Source.from_string(":a", path: "a.exs"))
{:error, %Rewrite.Error{reason: :overwrites, path: "a.exs"}}
```
```

--------------------------------

### Rewrite write_all Function

Source: https://hexdocs.pm/rewrite/Rewrite

The `write_all/2` function writes all sources within the specified `rewrite` project to disk. It accepts options for the write operation.

```elixir
write_all(rewrite, opts \ [])
```

--------------------------------

### from_sources! - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Creates a Rewrite project from sources, similar to from_sources/2. This version raises a Rewrite.Error exception upon failure.

```APIDOC
@spec from_sources!([Rewrite.Source.t()], opts()) :: t()
```

--------------------------------

### Write Source to File

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates writing a Source struct to a file, updating its content, and verifying the write operation. Includes handling cases where the file path is not set or needs to be updated.

```Elixir
iex> ":test" |> Source.from_string() |> Source.write()
{:error, %SourceError{reason: :nopath, path: nil, action: :write}}

iex> path = "tmp/foo.txt"
iex> File.write(path, "foo")
iex> source = path |> Source.read!() |> Source.update(:content, "bar")
iex> Source.updated?(source)
true
iex> {:ok, source} = Source.write(source)
iex> File.read(path)
{:ok, "bar\n"}
iex> Source.updated?(source)
false

iex> source = Source.from_string("bar")
iex> Source.write(source)
{:error, %SourceError{reason: :nopath, path: nil, action: :write}}
iex> source |> Source.update(:path, "tmp/bar.txt") |> Source.write()
iex> File.read("tmp/bar.txt")
{:ok, "bar\n"}
```

--------------------------------

### Rewrite.Source - Creation and Reading

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Functions for creating and reading source content. `read!/2` creates a source from a file path, while `from_string/2` creates one from a string.

```APIDOC
read!(path, opts \ []) :: %Rewrite.Source{}
  - Creates a new `%Source{}` from the given `path`.

from_string(content, opts \ []) :: %Rewrite.Source{}
  - Creates a new `%Source{}` from the given `string`.
```

--------------------------------

### Elixir Source AST Handling

Source: https://hexdocs.pm/rewrite/Rewrite.Source.Ex

Demonstrates how to create and update Elixir source code representations using Rewrite.Source.Ex, including managing the `:quoted` AST field and its synchronization.

```elixir
iex> source = Source.Ex.from_string("Enum.reverse(list)")
iex> Source.get(source, :quoted)
{{:., [trailing_comments: [], line: 1, column: 5],
  [
    {:__aliases__,
     [
       trailing_comments: [],
       leading_comments: [],
       last: [line: 1, column: 1],
       line: 1,
       column: 1
     ],
     [:Enum]},
    :reverse
  ]},
 [
   trailing_comments: [],
   leading_comments: [],
   closing: [line: 1, column: 18],
   line: 1,
   column: 1
 ],
 [{:list, [trailing_comments: [], leading_comments: [], line: 1, column: 14], nil}]}
iex> quoted = Code.string_to_quoted!("""
defmodule MyApp.New do
  def      foo do
  :foo
end
end
""")
iex> source = Source.update(source, :quoted, quoted)
iex> Source.updated?(source)
true
iex> Source.get(source, :content)
"""
defmodule MyApp.New do
  def foo do
    :foo
  end
end
"""
iex> Source.get(source, :quoted) == quoted
false
```

```elixir
iex> project = Rewrite.new(filetypes: [{Source.Ex, resync_quoted: false}])
iex> path = "test/fixtures/source/simple.ex"
iex> project = Rewrite.read!(project, path)
iex> source = Rewrite.source!(project, path)
iex> quoted = Code.string_to_quoted!("""
defmodule MyApp.New do
  def      foo do
  :foo
end
end
""")
iex> source = Source.update(source, :quoted, quoted)
iex> Source.get(source, :quoted) == quoted
true
```

--------------------------------

### Rewrite Write Functions

Source: https://hexdocs.pm/rewrite/Rewrite

Handles writing source files to disk. `write/3` returns {:ok, t} or {:error, ...}, while `write!/3` raises exceptions. `write_all/2` writes all sources, with options to exclude files or force writing.

```APIDOC
write(rewrite, path, force \ nil)
  @spec write(t(), Path.t() | Rewrite.Source.t(), nil | :force) ::
    {:ok, t()} | {:error, Rewrite.Error.t() | Rewrite.SourceError.t()}
  Writes a source to disk. Expects a path or a %Source{}.
  If the source is not part of the project, it is added. Returns {:ok, rewrite} on success.
  Parameters:
    - rewrite: The rewrite project.
    - path: The source file path or a %Source{} struct.
    - force: Optional. If nil, only writes changed files. If :force, writes all files.
  Returns: {:ok, t()} if written successfully, or {:error, ...} on failure.
  See also: Source.write/2.

write!(rewrite, source, force \ nil)
  @spec write!(t(), Path.t() | Rewrite.Source.t(), nil | :force) :: t()
  The same as write/3 but raises an exception in case of an error.

write_all(rewrite, opts \ [])
  @spec write_all(t(), opts()) :: {:ok, t()} | {:error, [Rewrite.SourceError.t()], t()}
  Writes all sources in the rewrite project to disk. Calls Rewrite.Source.write/1 on all sources.
  Returns {:ok, rewrite} if all sources are written successfully.
  Returns {:error, reasons, rewrite} where rewrite is updated for successfully written sources.
  Options:
    - exclude: A list of paths to exclude from writing.
    - force: Defaults to false. Forces writing of unchanged files.
```

--------------------------------

### Source Creation and Management

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Provides functions for creating, reading, updating, and deleting source code representations. Includes methods for initializing from strings or files, managing content, paths, owners, and private data.

```APIDOC
Source Module API:

# from_string(content, opts \ [])
@spec from_string(String.t(), opts()) :: t()
Creates a new %Source{} from the given string.

Options:
* :owner - an association to the module that owns the source.
* :dot_formatter - a formatter for the source.
* :path - the path of the source.

# read!(path, opts \ [])
@spec read!(Path.t(), opts()) :: t()
Creates a new %Source{} from the given path.

# update(source, key, value)
@spec update(t(), key(), value()) :: t()
Updates a specific key within the source, returning a new version.

# put_private(source, key, value)
@spec put_private(t(), key(), value()) :: t()
Assigns a private key and value to the source for user-defined storage.

# rm(source)
@spec rm(t()) :: :ok | {:error, Rewrite.SourceError.t()}
Tries to delete the file associated with the source.

# rm!(source)
@spec rm!(t()) :: :ok
Same as rm/1, but raises a Rewrite.SourceError exception on failure.

# touch(source)
@spec touch(t()) :: t()
Sets the timestamp to the current POSIX timestamp without touching the underlying file.

# touch(source, timestamp)
@spec touch(t(), timestamp()) :: t()
Sets the timestamp of the given source to the provided timestamp without touching the underlying file.
```

--------------------------------

### Move Source File

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Illustrates how to read a source file, update its path to a new location, and write it, effectively moving the file. It also shows how to perform this move operation without removing the original file.

```Elixir
iex> path = "tmp/ping.txt"
iex> File.write(path, "ping")
iex> source = Source.read!(path)
iex> new_path = "tmp/pong.ex"
iex> source = Source.update(source, :path, new_path)
iex> Source.write(source)
iex> File.exists?(path)
false
iex> File.read(new_path)
{:ok, "ping\n"}

iex> path = "tmp/ping.txt"
iex> File.write(path, "ping")
iex> source = Source.read!(path)
iex> new_path = "tmp/pong.ex"
iex> source = Source.update(source, :path, new_path)
iex> Source.write(source, rm: false)
iex> File.exists?(path)
true
iex> File.read(new_path)
{:ok, "ping\n"}
```

--------------------------------

### Elixir Specs: create/2 and create!/2

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Creates a DotFormatter struct from configuration options. `create/2` returns an {:ok, t()} or {:error, ...} tuple, while `create!/2` raises an exception on failure. Both accept rewrite configurations and keyword options.

```APIDOC
@spec create(
  Rewrite.t() | nil,
  keyword()
) :: {:ok, t()} | {:error, Rewrite.DotFormatterError.t()}

Returns a `%DotFormatter` for the given `config`.

The `opts` has the same format as the `.formatter.exs` file.

@spec create!(Rewrite.t() | nil, keyword()) :: t()

Same as [`create/2`](#create/2), but raises a [`Rewrite.DotFormatterError`](Rewrite.DotFormatterError.html) exception
in case of failure.
```

--------------------------------

### new - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Creates an empty Rewrite project. Supports options like :filetypes for custom source handling and :dot_formatter for source formatting.

```APIDOC
@spec new(keyword()) :: t()
```

--------------------------------

### new! - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Creates a Rewrite project from given inputs, which can be a single input or a list. Accepts options similar to new/1, including an 'exclude' option for paths.

```APIDOC
@spec new!(input() | [input()], opts()) :: t()
```

--------------------------------

### Read Sources into Project

Source: https://hexdocs.pm/rewrite/Rewrite

Reads specified inputs and adds their sources to the project if they haven't been read already. Supports forcing updates and excluding specific paths or glob expressions. Returns the updated project.

```elixir
@spec read!(t(), input() | [input()], opts() \ []) :: t()

Reads the given `input`/`inputs` and adds the source/sources to the `project`
when not already readed.

## Options

* `:force`, default: `false` - forces the reading of sources. With
  `force: true` updates and issues for an already existing source are
  deleted.
* `:exclude` - a list of paths and/or glob expressions to exclude sources
  from the project. The option also accepts a predicate function which is
  called for each source path. The exclusion takes place before the file is
  read.
```

--------------------------------

### new_source - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Creates a new source and adds it to the Rewrite project. It uses the project's :filetypes option and merges any specified options. Use create_source/4 if not inserting directly.

```APIDOC
@spec new_source(t(), Path.t(), String.t(), opts()) ::
  {:ok, t()} | {:error, Rewrite.Error.t()}
```

--------------------------------

### Rewrite format Functions

Source: https://hexdocs.pm/rewrite/Rewrite

Formats the entire rewrite project using a specified dot formatter or the project's default. `format/2` returns an `:ok` tuple with the formatted project or an error tuple. `format!/2` is a non-returning variant that raises an exception on error.

```APIDOC
format(rewrite, opts \ [])
  @spec format(t(), opts()) :: {:ok, t()} | {:error, term()}
  Formats the given `rewrite` project with the given `dot_formatter`.
  Uses the formatter from [`dot_formatter/2`](#dot_formatter/2) if no formatter ist set by
  `:dot_formatter` in the options. The other options are the same as for
  `DotFormatter.read!/2`.

format!(rewrite, opts \ [])
  @spec format!(t(), opts()) :: t()
  The same as [`format/2`](#format/2) but raises an exception in case of an error.
```

--------------------------------

### Reading Formatter Configurations

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Functions to read `.formatter.exs` files, either from the current directory or a specified project. Includes variants that return {:ok, DotFormatter} or raise exceptions on failure, with options to manage plugins and dependencies.

```APIDOC
read(rewrite \ nil, opts \ [])
  @spec read(rewrite :: Rewrite.t() | keyword() | nil, keyword()) :: {:ok, t()} | {:error, Rewrite.DotFormatterError.t()}
  Reads the .formatter.exs file in the current directory or the given %Rewrite{} project. If a %Rewrite{} project is given, the formatter is searched in the project and the latest version from the source is used. As a fallback, it will search the file system for the required files. The function returns a %DotFormatter{} struct with all sub-formatters.
  Options:
  * remove_plugins - a list of plugins to remove from the formatter.
  * replace_plugins - a list of {old, new} tuples to replace plugins in the formatter.
  * ignore_unknown_deps - ignores unknown dependencies in :import_deps when set to true. Defaults to false.
  * ignore_missing_sub_formatters - ignores missing sub formatters when set to true, Defaults to false.

read!(rewrite \ nil, opts \ [])
  @spec read!(rewrite :: Rewrite.t() | nil, keyword()) :: t()
  Same as read/2, but raises a Rewrite.DotFormatterError exception in case of failure.
```

--------------------------------

### Elixir Callback: format/2

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Formats a given string with specified options. This callback receives a string and a keyword list of options, returning the formatted string.

```APIDOC
@callback format(
  String.t(),
  keyword()
) :: String.t()

Receives a string to be formatted with options and returns said string.
```

--------------------------------

### Rewrite.Source - Formatting and Diffing

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Functions for formatting the source content and generating diffs. `format/2` formats the source, while `diff/2` returns iodata representing all changes.

```APIDOC
diff(source, opts \ []) :: iodata()
  - Returns iodata showing all diffs of the given `source`.

format(source, opts \ []) :: iodata()
  - Formats the given `source`.

format!(source, opts \ []) :: iodata()
  - Same as `format/2`, but raises an exception in case of failure.
```

--------------------------------

### paths - Elixir Rewrite

Source: https://hexdocs.pm/rewrite/Rewrite

Returns a sorted list of all paths present in the Rewrite project. This provides a quick overview of the files managed by the project.

```APIDOC
@spec paths(t()) :: [Path.t()]
```

--------------------------------

### Put Source (Raises Exception)

Source: https://hexdocs.pm/rewrite/Rewrite

Identical to `put/2`, but raises a `Rewrite.Error` exception upon failure instead of returning an error tuple. This is useful for contexts where an error should halt execution.

```elixir
@spec put!(t(), Rewrite.Source.t()) :: t()

Same as [`put/2`](#put/2), but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
```

--------------------------------

### Write Source with Conflict Handling

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Demonstrates the behavior of writing a Source struct when the target file has been modified externally. It shows the error raised on conflict and how to override it using the `force: true` option.

```Elixir
iex> path = "tmp/ping.txt"
iex> File.write(path, "ping")
iex> source = path |> Source.read!() |> Source.update(:content, "peng")
iex> File.write(path, "pong")
iex> Source.write(source)
{:error, %SourceError{reason: :changed, path: "tmp/ping.txt", action: :write}}
iex> {:ok, _source} = Source.write(source, force: true)
```

--------------------------------

### Rewrite create_source Function

Source: https://hexdocs.pm/rewrite/Rewrite

Creates a new `%Source{}` struct without immediately adding it to the `rewrite` project. It uses project filetype options and merges them with provided options. It does not check for existing sources with the same path.

```APIDOC
create_source(rewrite, path, content, opts \ [])
  @spec create_source(t(), Path.t() | nil, String.t(), opts()) :: Rewrite.Source.t()
  Creates a new `%Source{}` without putting it to the `%Rewrite{}` project.
  The `:filetypes` option of the project is used to create the source. If
  options have been specified for the file type, the given options will be
  merged into those options. If no `path` is given, the default file type is
  created.
  The function does not check whether the `%Rewrite{}` project already has a
  `%Source{}` with the specified path.
  Use [`new_source/4`](#new_source/4) if the source is to be inserted directly into the project.
```

--------------------------------

### Rewrite Project API

Source: https://hexdocs.pm/rewrite/Rewrite

Provides a comprehensive set of functions for interacting with and managing Rewrite projects and their sources. This includes operations like creating, deleting, formatting, and querying source files, as well as project-level manipulations.

```APIDOC
Rewrite Project API:

count(rewrite, extname)
  - Counts the sources with the given `extname` in the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - extname: The file extension to count.

create_source(rewrite, path, content, opts \ [])
  - Creates a new `%Source{}` without putting it to the `%Rewrite{}` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path for the new source.
    - content: The content of the new source.
    - opts: Optional arguments.

delete(rewrite, path)
  - Deletes the source for the given `path` from the `rewrite`.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source to delete.

dot_formatter(rewrite)
  - Returns the `DotFormatter` for the given `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
  - Returns: The DotFormatter.

dot_formatter(rewrite, dot_formatter)
  - Sets a `dot_formatter` for the given `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - dot_formatter: The DotFormatter to set.

drop(rewrite, paths)
  - Drops the sources with the given `paths` from the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - paths: A list of paths to drop.

extension_for_file(extensions, path)
  - Returns the extension of the given `file`.
  - Parameters:
    - extensions: A list of extensions.
    - path: The file path.

format(rewrite, opts \ [])
  - Formats the given `rewrite` project with the given `dot_formatter`.
  - Parameters:
    - rewrite: The Rewrite project.
    - opts: Optional arguments for formatting.

format!(rewrite, opts \ [])
  - The same as `format/2` but raises an exception in case of an error.
  - Parameters:
    - rewrite: The Rewrite project.
    - opts: Optional arguments for formatting.

format_source(rewrite, file, opts \ [])
  - Formats a source in a `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - file: The file to format.
    - opts: Optional arguments for formatting.

format_source!(rewrite, file, opts \ [])
  - The same as `format_source/3` but raises an exception in case of an error.
  - Parameters:
    - rewrite: The Rewrite project.
    - file: The file to format.
    - opts: Optional arguments for formatting.

from_sources(sources, opts \ [])
  - Creates a `%Rewrite{}` from the given sources.
  - Parameters:
    - sources: A list of sources.
    - opts: Optional arguments.

from_sources!(sources, opts \ [])
  - Same as `from_sources/2`, but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
  - Parameters:
    - sources: A list of sources.
    - opts: Optional arguments.

has_source?(rewrite, path)
  - Returns `true` when the `%Rewrite{}` contains a `%Source{}` with the given `path`.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path to check.

issues?(rewrite)
  - Returns `true` if any source has one or more issues.
  - Parameters:
    - rewrite: The Rewrite project.

map(rewrite, fun)
  - Invokes `fun` for each `source` in the `rewrite` project and updates the `rewirte` project with the result of `fun`.
  - Parameters:
    - rewrite: The Rewrite project.
    - fun: The function to apply to each source.

map!(rewrite, fun)
  - Return a `rewrite` project where each `source` is the result of invoking `fun` on each `source` of the given `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - fun: The function to apply to each source.

move(rewrite, from, to, by \ Rewrite)
  - Moves a source from one path to another.
  - Parameters:
    - rewrite: The Rewrite project.
    - from: The original path of the source.
    - to: The new path for the source.
    - by: The module to use for moving (defaults to Rewrite).

move!(rewrite, from, to, by \ Rewrite)
  - Same as `move/4`, but raises an exception in case of failure.
  - Parameters:
    - rewrite: The Rewrite project.
    - from: The original path of the source.
    - to: The new path for the source.
    - by: The module to use for moving (defaults to Rewrite).

new(opts \ [])
  - Creates an empty project.
  - Parameters:
    - opts: Optional arguments.

new!(inputs, opts \ [])
  - Creates a `%Rewrite{}` from the given `inputs`.
  - Parameters:
    - inputs: The inputs to create the project from.
    - opts: Optional arguments.

new_source(rewrite, path, content, opts \ [])
  - Creates a new `%Source{}` and puts the source to the `%Rewrite{}` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path for the new source.
    - content: The content of the new source.
    - opts: Optional arguments.

new_source!(rewrite, path, content, opts \ [])
  - Same as `new_source/4`, but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path for the new source.
    - content: The content of the new source.
    - opts: Optional arguments.

paths(rewrite)
  - Returns a sorted list of all paths in the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
  - Returns: A list of paths.

put(rewrite, source)
  - Puts the given `source` to the given `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to put.

put!(rewrite, source)
  - Same as `put/2`, but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to put.

read!(rewrite, inputs, opts \ [])
  - Reads the given `input`/`inputs` and adds the source/sources to the `project` when not already readed.
  - Parameters:
    - rewrite: The Rewrite project.
    - inputs: The input(s) to read.
    - opts: Optional arguments.

rm(rewrite, source)
  - Tries to delete the `source` file in the file system and removes the `source` from the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to remove.

rm!(rewrite, source)
  - Same as `source/2`, but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to remove.

source(rewrite, path)
  - Returns the `%Rewrite.Source{}` for the given `path`.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source.
  - Returns: The Source struct.

source!(rewrite, path)
  - Same as `source/2`, but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of failure.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source.

sources(rewrite)
  - Returns all sources sorted by path.
  - Parameters:
    - rewrite: The Rewrite project.
  - Returns: A list of sources.

update(rewrite, source)
  - Updates the given `source` in the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to update.

update(rewrite, path, source)
  - Updates a source for the given `path` in the `rewrite` project.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source to update.
    - source: The new source data.

update!(rewrite, source)
  - The same as `update/2` but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of an error.
  - Parameters:
    - rewrite: The Rewrite project.
    - source: The source to update.

update!(rewrite, path, new)
  - The same as `update/3` but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of an error.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source to update.
    - new: The new source data.

update_source(rewrite, path, key, fun, opts \ [])
  - Updates the source for the given `path` and `key` with the given `fun`.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source.
    - key: The key within the source to update.
    - fun: The function to apply for updating.
    - opts: Optional arguments.

update_source!(rewrite, path, key, fun, opts \ [])
  - The same as `update_source/5` but raises a [`Rewrite.Error`](Rewrite.Error.html) exception in case of an error.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source.
    - key: The key within the source to update.
    - fun: The function to apply for updating.
    - opts: Optional arguments.

updated?(rewrite)
  - Returns `true` if any source in the `rewrite` project returns `true` for `Source.updated?/1`.
  - Parameters:
    - rewrite: The Rewrite project.

write(rewrite, path, force \ nil)
  - Writes a source to disk.
  - Parameters:
    - rewrite: The Rewrite project.
    - path: The path of the source to write.
    - force: Whether to force writing (defaults to nil).

```

--------------------------------

### Elixir Callback: features/1

Source: https://hexdocs.pm/rewrite/Rewrite.DotFormatter

Defines the features a plugin integrates with. It returns a list of atoms representing supported features and a list of binary extensions.

```APIDOC
@callback features(Keyword.t()) :: [sigils: [atom()], extensions: [binary()]]

Returns which features this plugin should plug into.
```

--------------------------------

### Rewrite.Source.write! API

Source: https://hexdocs.pm/rewrite/Rewrite.Source

Provides the type specification and description for the `write!/1` function in the Rewrite.Source module. This function is equivalent to `write/1` but raises a `Rewrite.SourceError` on failure instead of returning an error tuple.

```APIDOC
@spec write!(t()) :: t()

Same as [`write/1`](#write/1), but raises a [`Rewrite.SourceError`](Rewrite.SourceError.html) exception in case of failure.
```
Tokens:
Raw