Search documentation of Ragex

# Ragex.Editor.Core (Ragex v0.4.0)

View Source

Core editing functionality with atomic operations and validation.

Provides safe file editing with:

- Automatic backups before editing
- Atomic write operations
- Concurrent modification detection
- Rollback support
- Integration with validation pipeline

## Summary

### Functions

edit_file(path, changes, opts \\ [])

Edits a file by applying a list of changes.

history(path, opts \\ [])

Gets editing history (backups) for a file.

rollback(path, opts \\ [])

Rolls back the most recent edit to a file.

validate_changes(path, changes, opts \\ [])

Validates changes without applying them.

## Functions

# edit_file(path, changes, opts \\ [])

    @spec edit_file(String.t(), [Ragex.Editor.Types.change()], keyword()) ::
      {:ok, Ragex.Editor.Types.edit_result()} | {:error, term()}

Edits a file by applying a list of changes.

## Parameters

- `path`: Path to the file to edit
- `changes`: List of change structs (see `Types`)
- `opts`: Options
  - `:validate` - Validate changes before applying (default: true)
  - `:create_backup` - Create backup before editing (default: true)
  - `:format` - Format code after editing (default: false)
  - `:validator` - Custom validator module (optional)
  - `:language` - Explicit language for validation (optional, auto-detected from file extension)

## Validation

When validation is enabled (default), the validator is automatically selected based on file extension. Supports: Elixir (.ex, .exs), Erlang (.erl, .hrl), Python (.py), JavaScript (.js, .jsx, .ts, .tsx, .mjs, .cjs)

## Returns

- `{:ok, result}` on success
- `{:error, reason}` on failure

## Examples

    iex> changes = [Types.replace(10, 15, "new content")]
    iex> Core.edit_file("lib/my_file.ex", changes)
    {:ok, %{path: "lib/my_file.ex", changes_applied: 1, ...}}

    iex> # Disable validation
    iex> Core.edit_file("lib/file.ex", changes, validate: false)
    {:ok, %{...}}

# history(path, opts \\ [])

    @spec history(
      String.t(),
      keyword()
    ) :: {:ok, [Ragex.Editor.Types.backup_info()]} | {:error, term()}

Gets editing history (backups) for a file.

## Parameters

- `path`: Path to the file
- `opts`: Options passed to `Backup.list/2`

## Returns

List of backup info structs.

# rollback(path, opts \\ [])

    @spec rollback(
      String.t(),
      keyword()
    ) :: {:ok, Ragex.Editor.Types.backup_info()} | {:error, term()}

Rolls back the most recent edit to a file.

## Parameters

- `path`: Path to the file
- `opts`: Options
  - `:backup_id` - Specific backup to restore (optional)

## Returns

- `{:ok, backup_info}` on success
- `{:error, reason}` on failure

# validate_changes(path, changes, opts \\ [])

    @spec validate_changes(String.t(), [Ragex.Editor.Types.change()], keyword()) ::
      :ok | {:error, [Ragex.Editor.Types.validation_error()]}

Validates changes without applying them.

## Parameters

- `path`: Path to the file (for context and validator auto-detection)
- `changes`: List of change structs
- `opts`: Options
  - `:validator` - Custom validator module (optional)
  - `:language` - Explicit language for validation (optional)

## Returns

- `:ok` if valid
- `{:error, errors}` if invalid