# `Minga.API`
[🔗](https://github.com/jsmestad/minga/blob/main/lib/minga/api.ex#L1)

Public API for interacting with the editor from eval (`M-:`).

Provides user-friendly functions for common editor operations. All
functions default to the running `MingaEditor` GenServer and the
active buffer. Pass an explicit `editor` PID to target a different
instance.

## Usage from eval

    # M-: Minga.API.insert("hello")
    # M-: Minga.API.save()
    # M-: Minga.API.cursor()
    # M-: Minga.API.open("lib/minga.ex")

## Error handling

Functions return `{:ok, result}` or `{:error, reason}` where
possible. They never raise on bad input.

# `editor`

```elixir
@type editor() :: GenServer.server()
```

Editor GenServer reference.

# `content`

```elixir
@spec content(editor()) :: {:ok, String.t()} | {:error, :no_buffer}
```

Returns the full content of the active buffer.

## Examples

    {:ok, text} = Minga.API.content()

# `cursor`

```elixir
@spec cursor(editor()) ::
  {:ok, {non_neg_integer(), non_neg_integer()}} | {:error, :no_buffer}
```

Returns the current cursor position as `{line, col}` (0-indexed).

## Examples

    {:ok, {line, col}} = Minga.API.cursor()

# `execute`

```elixir
@spec execute(Minga.Mode.command(), editor()) :: :ok
```

Executes an editor command by name.

Commands are the same atoms used internally (e.g. `:save`, `:undo`,
`:move_down`, `:buffer_next`). See `Minga.Command.Registry` for
the full list.

## Examples

    Minga.API.execute(:undo)
    Minga.API.execute(:buffer_next)
    Minga.API.execute({:goto_line, 42})

# `fold_all`

```elixir
@spec fold_all(editor()) :: :ok
```

Folds all available ranges in the active window.

# `fold_toggle`

```elixir
@spec fold_toggle(editor()) :: :ok
```

Toggles the fold at the cursor line in the active window.

# `insert`

```elixir
@spec insert(String.t(), editor()) :: :ok | {:error, :no_buffer}
```

Inserts text at the current cursor position in the active buffer.

## Examples

    Minga.API.insert("hello world")
    Minga.API.insert("\n")  # insert a newline

# `line_count`

```elixir
@spec line_count(editor()) :: {:ok, non_neg_integer()} | {:error, :no_buffer}
```

Returns the number of lines in the active buffer.

## Examples

    {:ok, count} = Minga.API.line_count()

# `message`

```elixir
@spec message(String.t(), editor()) :: :ok
```

Logs a message to the `*Messages*` buffer.

## Examples

    Minga.API.message("Build completed!")

# `mode`

```elixir
@spec mode(editor()) :: Minga.Mode.mode()
```

Returns the current editor mode (e.g. `:normal`, `:insert`, `:visual`).

## Examples

    :normal = Minga.API.mode()

# `move_to`

```elixir
@spec move_to(non_neg_integer(), non_neg_integer(), editor()) ::
  :ok | {:error, :no_buffer}
```

Moves the cursor to the given `{line, col}` position (0-indexed).

## Examples

    Minga.API.move_to(0, 0)   # go to start of file
    Minga.API.move_to(10, 5)  # line 11, column 6

# `open`

```elixir
@spec open(String.t(), editor()) :: :ok | {:error, term()}
```

Opens a file in the editor. If the file is already open, switches to it.

## Examples

    :ok = Minga.API.open("lib/minga.ex")

# `save`

```elixir
@spec save(editor()) :: :ok | {:error, term()}
```

Saves the active buffer to disk.

## Examples

    :ok = Minga.API.save()

# `set_fold_ranges`

```elixir
@spec set_fold_ranges([Minga.Editing.Fold.Range.t()], editor()) :: :ok
```

Sets the available fold ranges for the active window.

Extensions call this to provide fold ranges computed from their own
logic (e.g., org-mode heading ranges). The editor will preserve any
existing folds that match the new ranges.

# `unfold_all`

```elixir
@spec unfold_all(editor()) :: :ok
```

Unfolds all folds in the active window.

---

*Consult [api-reference.md](api-reference.md) for complete listing*