L'API Lua di Neovim

Neovim integra un runtime LuaJIT, rendendo Lua il linguaggio nativo per gli script insieme a Vimscript. Gli autori dei plugin preferiscono Lua per la sua velocità, per le vere strutture dati e per il suo sistema di moduli pulito.

La tabella globale vim è il punto di accesso a tutto: stato dell'editor, API, opzioni e funzioni di supporto della libreria standard. Padroneggiarla è la base per lo sviluppo moderno dei plugin.

vim.api espone l'API remota di basso livello: ogni funzione ha il prefisso nvim_. Sono le stesse chiamate utilizzate dai client esterni tramite RPC, ma all'interno del processo vengono eseguite istantaneamente.

Funzioni come nvim_get_current_buf, nvim_buf_set_lines e nvim_command offrono un controllo preciso. Sono stabili, ben documentate e costituiscono la base dei plugin più avanzati.

vim.fn fa da ponte verso le funzioni integrate di Vimscript. Qualsiasi funzione chiamabile in Vimscript, come expand() o fnamemodify(), è accessibile come vim.fn.expand(...).

È indispensabile quando non esiste ancora un'API nativa. Gli argomenti e i valori restituiti vengono convertiti automaticamente tra i tipi Lua e Vimscript.

Le opzioni si impostano tramite metatabelle. vim.o riguarda le opzioni globali, vim.bo quelle locali al buffer e vim.wo quelle locali alla finestra.

Assegnare un valore è semplice quanto scrivere in un campo. Questo sostituisce le verbose chiamate a nvim_set_option e rende il codice di configurazione più naturale da leggere.

vim.g legge e scrive le variabili Vim globali. I plugin espongono comunemente qui le opzioni di configurazione, ad esempio vim.g.myplugin_enabled.

La lettura di una variabile non impostata restituisce nil, quindi utilizzi dei valori predefiniti come protezione. Esistono anche le varianti con ambito di buffer e finestra, vim.b e vim.w.

Utilizzi vim.notify per mostrare messaggi all'utente. Accetta una stringa di messaggio e un livello di log facoltativo proveniente da vim.log.levels.

Plugin manager come noice o notify possono intercettare questi messaggi per offrire un'interfaccia migliore. Per l'output destinato all'utente, preferisca vim.notify a un semplice print.

Alcune chiamate API non sono consentite nei contesti di eventi rapidi, ad esempio all'interno di determinati callback. vim.schedule rimanda l'esecuzione di una funzione al ciclo principale, dove l'intera API può essere utilizzata in sicurezza.

In questo modo si evitano i temuti errori "E5560" quando si modificano i buffer da contesti asincroni o di autocomandi.

nvim_create_autocmd registra i gestori degli eventi. Li raggruppi con nvim_create_augroup e imposti clear = true per evitare duplicati durante il ricaricamento.

Il callback riceve una tabella di eventi con campi come buf e match, che forniscono al gestore il contesto preciso.

Neovim include una ricca libreria standard. vim.tbl_extend, vim.tbl_keys e vim.split coprono le operazioni più comuni su tabelle e stringhe.

vim.tbl_deep_extend('force', defaults, opts) è il modo canonico per unire la configurazione dell'utente ai valori predefiniti del plugin.

vim.inspect serializza qualsiasi valore Lua in una stringa leggibile, comprese le tabelle annidate. È il modo più rapido per capire la struttura dei valori restituiti dall'API.

Lo abbini a :lua print(vim.inspect(...)) oppure a :lua= expr nelle versioni recenti di Neovim per eseguire ispezioni rapide durante lo sviluppo.

Preferisca vim.api per le operazioni stabili e strutturate. Ricorra a vim.fn o vim.cmd quando non esiste una funzione nativa.

vim.cmd esegue comandi Ex sotto forma di stringhe ed è pratico per operazioni occasionali come vim.cmd('highlight ...'), ma consente meno introspezione rispetto alle chiamate API tipizzate.

Verifichi la sua comprensione delle API Lua di Neovim.

Ora conosce le superfici principali: vim.api per l'API nativa tipizzata, vim.fn per le funzioni Vimscript e vim.cmd per i comandi Ex.

Le opzioni passano attraverso vim.o/bo/wo, le variabili attraverso vim.g/b/w e funzioni di supporto come vim.tbl_deep_extend, vim.notify e vim.schedule completano il kit di strumenti dell'autore di plugin.