La API de Lua de Neovim

Neovim incorpora un entorno de ejecución LuaJIT, lo que convierte a Lua en el lenguaje de scripting nativo junto con Vimscript. Los autores de plugins prefieren Lua por su velocidad, sus estructuras de datos propiamente dichas y su sistema de módulos claro.

La tabla global vim es la puerta de entrada a todo: el estado del editor, la API, las opciones y las funciones auxiliares de la biblioteca estándar. Dominarla es la base del desarrollo moderno de plugins.

vim.api expone la API remota de bajo nivel: todas las funciones cuyo prefijo es nvim_. Son las mismas llamadas que los clientes externos usan a través de RPC, pero dentro del proceso se ejecutan al instante.

Funciones como nvim_get_current_buf, nvim_buf_set_lines y nvim_command ofrecen un control preciso. Son estables, están bien documentadas y constituyen la base de los plugins serios.

vim.fn conecta con las funciones integradas de Vimscript. Cualquier función que se pueda invocar en Vimscript, como expand() o fnamemodify(), está disponible como vim.fn.expand(...).

Esto resulta sumamente útil cuando todavía no existe una API nativa. Los argumentos y valores devueltos se convierten automáticamente entre los tipos de Lua y Vimscript.

Las opciones se establecen mediante metatablas. vim.o se aplica a las opciones globales, vim.bo a las locales del búfer y vim.wo a las locales de la ventana.

Asignar una opción es tan sencillo como escribir un campo. Esto sustituye a las llamadas más verbosas a nvim_set_option y resulta natural en el código de configuración.

vim.g lee y escribe variables globales de Vim. Los plugins suelen exponer aquí opciones de configuración, como vim.g.myplugin_enabled.

Leer una variable que no se ha establecido devuelve nil, por lo que debe protegerse con valores predeterminados. También existen variantes con ámbito de búfer y de ventana, vim.b y vim.w.

Use vim.notify para mostrar mensajes al usuario. Acepta una cadena de mensaje y un nivel de registro opcional de vim.log.levels.

Los gestores de plugins, como noice o notify, pueden interceptar estos mensajes para ofrecer una interfaz más agradable. Prefiera vim.notify a print sin formato para la salida destinada al usuario.

Algunas llamadas a la API están prohibidas en contextos de eventos rápidos, como dentro de ciertas devoluciones de llamada. vim.schedule aplaza una función al bucle principal, donde toda la API es segura.

Esto evita los temidos errores "E5560" al modificar búferes desde contextos asíncronos o de autocomandos.

nvim_create_autocmd registra controladores de eventos. Agrúpelos con nvim_create_augroup y establezca clear = true para evitar duplicados al recargar.

La devolución de llamada recibe una tabla de evento con campos como buf y match, lo que proporciona un contexto preciso para el controlador.

Neovim incluye una completa biblioteca estándar. vim.tbl_extend, vim.tbl_keys y vim.split cubren las operaciones habituales con tablas y cadenas.

vim.tbl_deep_extend('force', defaults, opts) es la forma canónica de combinar la configuración del usuario con los valores predeterminados del plugin.

vim.inspect serializa cualquier valor de Lua en una cadena legible, incluidas las tablas anidadas. Es la forma más rápida de comprender la estructura de los valores devueltos por la API.

Combínelo con :lua print(vim.inspect(...)) o con :lua= expr en las versiones recientes de Neovim para inspeccionar valores rápidamente durante el desarrollo.

Prefiera vim.api para las operaciones estables y estructuradas. Recurra a vim.fn o vim.cmd cuando no exista una función nativa.

vim.cmd ejecuta comandos ex como cadenas y resulta práctico para casos puntuales, como vim.cmd('highlight ...'), pero permite inspeccionar menos información que las llamadas a la API con tipos.

Compruebe cuánto domina la superficie de la API Lua de Neovim.

Ahora conoce las interfaces principales: vim.api para la API nativa con tipos, vim.fn para las funciones de Vimscript y vim.cmd para los comandos ex.

Las opciones se gestionan mediante vim.o/bo/wo, las variables mediante vim.g/b/w, y funciones auxiliares como vim.tbl_deep_extend, vim.notify y vim.schedule completan el conjunto de herramientas del autor de plugins.