# Редактор — `api.editor`

Группа `api.editor` управляет вкладками, текстом, gutter, подсветкой и
сохранением. LSP-серверы описаны отдельно в [lsp.md](lsp.md), привязки
клавиш редактора — в [keymap.md](keymap.md).

Номера вкладок нумеруются с нуля.

## Вкладки

| Метод | Описание |
| --- | --- |
| `api.editor:tabs()` | Список вкладок: `{{ index = 0, title = "main.rs", icon = "file" }, ...}` |
| `api.editor:active_tab()` | Индекс активной вкладки |
| `api.editor:set_active_tab(index)` | Сделать вкладку активной; `true`, если вкладка существует |
| `api.editor:next_tab()` | Переключить на следующую вкладку, вернуть индекс |
| `api.editor:previous_tab()` | Переключить на предыдущую вкладку, вернуть индекс |
| `api.editor:open_tab()` | Открыть пустую вкладку, вернуть индекс |
| `api.editor:open(path, position)` | Открыть файл с диска, вернуть индекс вкладки |
| `api.editor:close_tab(index)` | Закрыть вкладку; `true`, если вкладка закрыта |
| `api.editor:focus()` | Перевести фокус в редактор, не меняя вкладку и курсор |

Если файла нет, `open` создаёт пустой буфер с таким именем — как в vim.
Язык подсветки определяется по расширению, если для него есть грамматика.
Первый аргумент принимает и строку `"src/main.rs"`, и массив сегментов
`{ "src", "main.rs" }`.

Второй аргумент `open` необязателен:

| Значение | Поведение |
| --- | --- |
| нет аргумента / `nil` | Открыть вкладку, не трогая фокус |
| `{}` | Перевести фокус в редактор, курсор оставить на месте |
| `{line, column}` | Перевести фокус и поставить курсор (с нуля) |

```lua
api.editor:open("src/main.rs")          -- открыть, не трогая фокус
api.editor:open("src/main.rs", {})      -- фокус в редактор, курсор на месте
api.editor:open("src/main.rs", {4, 2})  -- фокус в редактор, курсор на строку 4, столбец 2
```

Строка и столбец нумеруются с нуля, как в диагностике LSP; столбец считается
в UTF-16.

## Иконки вкладок

Слева от названия вкладки показывается иконка; по умолчанию это `file`.
Имя — название иконки [Lucide](https://lucide.dev/icons/), регистр не важен.
Подчёркивания и пробелы считаются дефисом, а `icons/` и `.svg` можно не
писать: `file_code`, `file-code` и `icons/file-code.svg` равнозначны.

| Метод | Описание |
| --- | --- |
| `api.editor:set_tab_icon(index, name)` | Назначить иконку вкладке; `false`, если вкладки нет или иконка неизвестна |
| `api.editor:clear_tab_icon(index)` | Вернуть иконку по умолчанию (`file`) |
| `api.editor:tab_icon(index)` | Имя иконки вкладки или `nil`, если вкладки нет |

```lua
api.editor:set_tab_icon(0, "file-code")
api.editor:set_tab_icon(1, "book-open")
api.editor:clear_tab_icon(1)             -- снова "file"
```

## Иконки на полях редактора (gutter)

Слева от редактора есть узкая колонка с иконками. Методы действуют на
активную вкладку, а номера строк нумеруются с нуля, как в LSP. На одной строке
живёт одна иконка; повторный вызов заменяет прежнюю.

| Метод | Описание |
| --- | --- |
| `api.editor:set_gutter_icon(line, icon, color)` | Поставить иконку на строку; `color` необязателен (`#RGB`, `#RGBA`, `#RRGGBB`, `#RRGGBBAA`). Без цвета иконка рисуется цветом темы. `false` — иконка или цвет неизвестны |
| `api.editor:gutter_icon(line)` | Имя иконки на строке или `nil` |
| `api.editor:gutter_color(line)` | Цвет иконки или `nil`, если цвет не задан |
| `api.editor:clear_gutter_icon(line)` | Убрать иконку со строки; `false`, если её не было |
| `api.editor:clear_gutter()` | Убрать все иконки активной вкладки |

```lua
api.editor:set_gutter_icon(4, "circle", "#e5484d") -- красная точка на 5-й строке
api.editor:set_gutter_icon(9, "play")              -- цвет темы
api.editor:clear_gutter_icon(9)
```

Иконки привязаны к номерам строк и автоматически не сдвигаются при правке
текста: сценарий сам решает, когда их переставить. При прокрутке колонка
двигается вместе с редактором.

## Текст

| Метод | Описание |
| --- | --- |
| `api.editor:active_text()` | Текст активной вкладки |
| `api.editor:set_active_text(text)` | Заменить текст активной вкладки |

## Сохранение

| Метод | Описание |
| --- | --- |
| `api.editor:save()` | Сохранить активную вкладку в её файл |

Путь считается относительно текущего рабочего каталога процесса. При успешной
записи с вкладки снимается маркер несохранённых изменений.

## Подсветка синтаксиса

Подсветка по умолчанию выключена. Поддерживаемые языки: `rust`, `go`, `js`,
`json`, `python`, `lua`, `bash`, `yaml`, `make`, `dockerfile`, `sql`,
`markdown`, `css`, `c`, `cpp`, `html`, `xml`. Для `set_language` принимаются
и короткие имена (`rs`, `golang`, `javascript`, `py`, `sh`, `yml`, `makefile`,
`md`, `c++`…).

| Метод | Описание |
| --- | --- |
| `api.editor:set_language(index, "rust")` | Включить подсветку для вкладки; `false`, если вкладки нет или язык не поддерживается |
| `api.editor:language(index)` | Язык подсветки вкладки или `nil` |
| `api.editor:clear_language(index)` | Выключить подсветку для вкладки |

```lua
api.editor:set_language(0, "rust")
```

## Привязки редактора

`api.editor:map_key`, `api.editor:set_mode` и `api.editor:mode` работают так
же, как глобальные привязки из [keymap.md](keymap.md), но срабатывают
дополнительно к глобальным и только когда фокус находится в редакторе.

```lua
api.editor:map_key("", "<A-r>", function()
  api.editor:set_active_text("editor mode")
end)
```