API Lua для Neovim

Neovim встраивает среду выполнения LuaJIT, благодаря чему Lua становится встроенным языком сценариев наряду со скриптами Vim. Авторы плагинов предпочитают Lua за его скорость, полноценные структуры данных и ясную систему модулей.

Глобальная таблица vim открывает доступ ко всему: состоянию редактора, программному интерфейсу, параметрам и вспомогательным функциям стандартной библиотеки. Её освоение — основа современной разработки плагинов.

vim.api предоставляет низкоуровневый удалённый программный интерфейс: все функции с префиксом nvim_. Это те же вызовы, которые внешние клиенты используют через RPC, но внутри процесса они выполняются мгновенно.

Такие функции, как nvim_get_current_buf, nvim_buf_set_lines и nvim_command, обеспечивают точный контроль. Они стабильны, хорошо документированы и лежат в основе серьёзных плагинов.

vim.fn служит связующим звеном со встроенными функциями Vim. Любая функция, которую можно вызвать в Vim, например expand() или fnamemodify(), доступна как vim.fn.expand(...).

Это особенно полезно, когда собственного программного интерфейса ещё нет. Аргументы и возвращаемые значения автоматически преобразуются между типами Lua и Vim.

Параметры задаются через метатаблицы. vim.o обращается к глобальным параметрам, vim.bo — к параметрам буфера, а vim.wo — к параметрам окна.

Присваивание выполняется простой записью в поле. Это заменяет многословные вызовы nvim_set_option и делает код настройки более естественным.

vim.g читает и изменяет глобальные переменные Vim. Плагины часто хранят здесь переключатели настроек, например vim.g.myplugin_enabled.

Чтение незаданной переменной возвращает nil, поэтому предусмотрите значения по умолчанию. Варианты с областью действия буфера и окна доступны как vim.b и vim.w.

Используйте vim.notify, чтобы показывать пользователю сообщения. Эта функция принимает строку сообщения и необязательный уровень журнала из vim.log.levels.

Менеджеры плагинов, такие как noice или notify, могут перехватывать эти сообщения и отображать их в более удобном интерфейсе. Для вывода пользователю предпочитайте vim.notify обычному print.

Некоторые вызовы программного интерфейса запрещены в контекстах быстрых событий, например внутри определённых обратных вызовов. vim.schedule откладывает выполнение функции до главного цикла, где весь программный интерфейс безопасен.

Это позволяет избежать печально известных ошибок "E5560" при изменении буферов из асинхронных контекстов или контекстов автокоманд.

nvim_create_autocmd регистрирует обработчики событий. Объединяйте их с помощью nvim_create_augroup и устанавливайте clear = true, чтобы при перезагрузке не появлялись дубликаты.

Обратный вызов получает таблицу события с такими полями, как buf и match, что обеспечивает точный контекст для обработчика.

Neovim поставляется с богатой стандартной библиотекой. vim.tbl_extend, vim.tbl_keys и vim.split охватывают распространённые операции с таблицами и строками.

vim.tbl_deep_extend('force', defaults, opts) — стандартный способ объединить пользовательскую конфигурацию с настройками плагина по умолчанию.

vim.inspect преобразует любое значение Lua в удобочитаемую строку, включая вложенные таблицы. Это самый быстрый способ понять структуру возвращаемых программным интерфейсом значений.

Используйте её вместе с :lua print(vim.inspect(...)) или :lua= expr в последних версиях Neovim для быстрой проверки во время разработки.

Предпочитайте vim.api для стабильных структурированных операций. Если собственной функции нет, используйте vim.fn или vim.cmd как запасной вариант.

vim.cmd выполняет команды ex в виде строк и удобен для разовых действий, например vim.cmd('highlight ...'), но его возможности для анализа ниже, чем у типизированных вызовов программного интерфейса.

Проверьте, насколько хорошо Вы понимаете программный интерфейс Neovim на Lua.

Теперь Вы знаете основные уровни программного интерфейса: vim.api для типизированного встроенного программного интерфейса, vim.fn для функций Vim и vim.cmd для команд ex.

Параметры задаются через vim.o/bo/wo, переменные — через vim.g/b/w, а такие вспомогательные средства, как vim.tbl_deep_extend, vim.notify и vim.schedule, дополняют набор инструментов автора плагина.