Lua API do Neovim

    Definição curta: A Lua API do Neovim é uma interface programática para controlar o editor usando a linguagem Lua. Permite configurar opções, criar comandos, interagir com buffers e muito mais.

    Antes de começar

    • Saber sair do Neovim (:q) e navegar em modo normal

    O que você vai aprender

    • Explicar vim.api com suas palavras
    • Explicar vim.fn com suas palavras
    • Explicar vim.opt com suas palavras
    • Localizar o assunto desta página no :help do seu próprio Neovim

    O que é

    Desde o Neovim 0.5+, Lua é suportado nativamente como linguagem de configuração. A Lua API é exposta no módulo vim global.

    Índice de sub-tópicos

    vim.api

    Funções de alto nível para interação com Neovim.

    vim.api.nvim_create_command('MyCommand', function(args)
  print("Args: " .. vim.inspect(args))
end, { bang = true })

vim.api.nvim_set_keymap('n', '<leader>x', ':MyCommand<CR>', { noremap = true })

    vim.fn

    Acessa funções Vim/Neovim internas.

    vim.fn.input("Prompt: ")  -- Prompt de entrada
vim.fn.expand("%:p")      -- Caminho completo do arquivo
vim.fn.line(".")          -- Linha atual

    vim.opt

    API para opções do editor.

    vim.opt.number = true
vim.opt.relativenumber = true
vim.opt.expandtab = true
vim.opt.shiftwidth = 2
vim.opt.tabstop = 2
vim.opt.smartindent = true

    vim.cmd

    Executar comandos Ex.

    vim.cmd("edit foo.txt")
vim.cmd("vsplit")
vim.cmd("normal! gg")

    vim.keymap.set

    Criar mapeamentos de teclas.

    vim.keymap.set('n', '<leader>ff', function()
  print("Hello")
end, { silent = true, desc = "Print hello" })

    Fluxo de configuração Lua

    flowchart TD
    A["init.lua"] --> B["vim.keymap.set"]
    A --> C["vim.opt"]
    A --> D["vim.api.nvim_create_*"]
    B --> E["Mapeamentos criados"]
    C --> F["Opções configuradas"]
    D --> G["Comandos/autocommands"]

    Erros comuns

    • Traduzir Vimscript linha a linha. Sai um Lua que funciona e que ninguém consegue ler. Vale repensar a estrutura junto.
    • Chamar vim.api quando existe vim.fn ou uma função de conveniência. A API de baixo nível é estável mas verbosa; nem tudo precisa dela.
    • Esquecer que init.lua roda na inicialização. Trabalho pesado ali atrasa a abertura do editor toda vez — veja Desempenho.

    Você aprendeu

    • vim.api
    • vim.fn
    • vim.opt
    • vim.cmd
    • vim.keymap.set

    Perguntas para reflexão

    1. O que vim.api resolve, e o que se perde sem isso?
    2. O que vim.fn resolve, e o que se perde sem isso?
    3. O que vim.opt resolve, e o que se perde sem isso?
    4. Qual parte desta página você conseguiria reproduzir sem consultar, direto no editor?

    Artigos relacionados

    Veja também

    Referências