A API Lua do Neovim

O Neovim incorpora um ambiente de execução LuaJIT, tornando Lua a linguagem nativa de scripts ao lado do Vimscript. Autores de plugins preferem Lua por sua velocidade, suas estruturas de dados reais e seu sistema de módulos limpo.

A tabela global vim é a porta de entrada para tudo: o estado do editor, a API, as opções e as funções auxiliares da biblioteca padrão. Dominá-la é a base do desenvolvimento moderno de plugins.

vim.api expõe a API remota de baixo nível: todas as funções com o prefixo nvim_. São as mesmas chamadas que clientes externos usam por RPC, mas, no mesmo processo, elas são executadas instantaneamente.

Funções como nvim_get_current_buf, nvim_buf_set_lines e nvim_command oferecem controle preciso. Elas são estáveis, bem documentadas e formam a base de plugins robustos.

vim.fn faz a ponte com as funções integradas do Vimscript. Tudo o que pode ser chamado no Vimscript, como expand() ou fnamemodify(), pode ser acessado como vim.fn.expand(...).

Isso é indispensável quando ainda não existe uma API nativa. Os argumentos e os valores retornados são convertidos automaticamente entre os tipos de Lua e do Vimscript.

As opções são definidas por meio de metatabelas. vim.o tem como alvo as opções globais, vim.bo as específicas do buffer e vim.wo as específicas da janela.

A atribuição é tão simples quanto escrever em um campo. Isso substitui as chamadas extensas de nvim_set_option e torna o código de configuração mais natural de ler.

vim.g lê e grava variáveis globais do Vim. Os plugins costumam expor aqui opções de configuração, como vim.g.myplugin_enabled.

Ler uma variável não definida retorna nil, portanto use valores padrão como proteção. Também existem variantes com escopo de buffer e de janela, disponíveis como vim.b e vim.w.

Use vim.notify para exibir mensagens ao usuário. Ela aceita uma cadeia de caracteres com a mensagem e um nível de registro opcional de vim.log.levels.

Gerenciadores de plugins como noice ou notify podem interceptar essas mensagens para oferecer uma interface mais agradável. Prefira vim.notify a print bruto para saídas exibidas ao usuário.

Algumas chamadas da API são proibidas em contextos de eventos rápidos, como dentro de certas funções de retorno. vim.schedule adia uma função para o loop principal, onde toda a API pode ser usada com segurança.

Isso evita os temidos erros "E5560" ao modificar buffers em contextos assíncronos ou de comandos automáticos.

nvim_create_autocmd registra manipuladores de eventos. Agrupe-os com nvim_create_augroup e defina clear = true para evitar duplicatas ao recarregar.

A função de retorno recebe uma tabela de eventos com campos como buf e match, fornecendo o contexto preciso para o seu manipulador.

O Neovim inclui uma biblioteca padrão abrangente. vim.tbl_extend, vim.tbl_keys e vim.split abrangem operações comuns com tabelas e cadeias de caracteres.

vim.tbl_deep_extend('force', defaults, opts) é a forma padrão de mesclar a configuração do usuário sobre os padrões do plugin.

vim.inspect serializa qualquer valor Lua em uma cadeia legível, incluindo tabelas aninhadas. É a maneira mais rápida de entender os formatos dos valores retornados pela API.

Combine-o com :lua print(vim.inspect(...)) ou :lua= expr nas versões recentes do Neovim para fazer uma inspeção rápida durante o desenvolvimento.

Dê preferência a vim.api para operações estruturadas e estáveis. Use vim.fn ou vim.cmd como alternativa quando não existir uma função nativa.

vim.cmd executa comandos ex como cadeias de caracteres e é útil para ações pontuais, como vim.cmd('highlight ...'), mas permite menos inspeção do que as chamadas de API tipadas.

Teste sua compreensão da API Lua do Neovim.

Agora você conhece as principais interfaces: vim.api para a API nativa tipada, vim.fn para funções do Vimscript e vim.cmd para comandos ex.

As opções passam por vim.o/bo/wo, as variáveis por vim.g/b/w, e funções auxiliares como vim.tbl_deep_extend, vim.notify e vim.schedule completam o conjunto de ferramentas de um autor de plugins.