Comandi e keymap

I comandi utente sono comandi preceduti da due punti che il plugin mette a disposizione, come :Format o :Telescope. Devono iniziare con una lettera maiuscola.

nvim_create_user_command li definisce in Lua, specificando un nome, un callback o una stringa e una tabella di opzioni. Questo sostituisce :command di Vimscript.

Imposti nargs per accettare gli argomenti: '0', '1', '*', '?' oppure '+'. Il callback riceve una tabella opts con args, fargs e bang.

fargs è l'elenco degli argomenti già suddiviso in base agli spazi bianchi, che nella maggior parte dei casi è proprio ciò che serve.

Passi range = true per accettare gli intervalli di righe; il callback leggerà quindi opts.line1 e opts.line2. Aggiunga bang = true per consentire :Cmd!, rilevato tramite opts.bang.

Questi flag permettono allo stesso comando di comportarsi in modo diverso per le selezioni visuali o per le varianti forzate.

Fornisca il completamento con il tasto Tab tramite l'opzione complete. Utilizzi valori integrati come 'file' o 'buffer', oppure una funzione Lua personalizzata.

Un completatore personalizzato riceve l'argomento parziale e la riga di comando, quindi restituisce un elenco di stringhe candidate.

Per limitare un comando a un solo buffer, utilizzi nvim_buf_create_user_command con l'handle del buffer. È una pratica comune nei plugin specifici per il tipo di file.

Ad esempio, un plugin Markdown potrebbe definire :Preview solo all'interno dei buffer Markdown, mantenendo pulito lo spazio dei nomi globale.

vim.keymap.set è l'API moderna per le mappature. Accetta una modalità, i tasti a sinistra, una stringa o una funzione Lua a destra e una tabella di opzioni.

A differenza del vecchio nvim_set_keymap, accetta direttamente un callback Lua come parte destra, senza bisogno di racchiuderlo in <cmd>lua.

L'argomento della modalità può essere una singola stringa come 'n' oppure una tabella come { 'n', 'v' } per eseguire la mappatura in più modalità contemporaneamente.

Modalità comuni: n normale, i inserimento, v visuale, x solo visuale, t terminale. Una stringa vuota '' indica le modalità normale, visuale e di attesa dell'operatore.

La tabella opts controlla il comportamento. silent = true nasconde l'eco del comando, noremap è true per impostazione predefinita, per maggiore sicurezza, e buffer = 0 limita la mappatura al buffer corrente.

Aggiunga sempre un desc, così l'output di which-key e di :map rimane leggibile.

Con expr = true, la funzione della parte destra restituisce i tasti da utilizzare. Questo consente di creare mappature intelligenti, ad esempio facendo comportare <Tab> in modo diverso quando è visibile un menu di completamento.

Restituisca una stringa vuota per non eseguire alcuna azione oppure i tasti letterali da inserire.

Rimuova una mappatura con vim.keymap.del, passando la stessa modalità e gli stessi tasti, oltre a un campo buffer se la mappatura era locale al buffer.

È utile nelle routine di pulizia o quando un plugin disattiva una funzionalità e deve ripristinare le associazioni originali dell'utente.

Un modello pulito consiste nel definire la logica una sola volta, esporla come comando utente e associare a quel comando un tasto. In questo modo si mantiene un'unica fonte di verità.

Associare il tasto a <cmd>Hello<cr> evita di uscire dalla modalità visuale ed è più prevedibile di :Hello<cr>.

Verifichi la sua comprensione dei comandi e delle mappature dei tasti.

Ora sa creare comandi con nvim_create_user_command, controllarli tramite nargs, range, bang e complete e limitarli a uno specifico buffer.

Per le mappature, vim.keymap.set accetta callback Lua, più modalità e opzioni come desc, silent, buffer ed expr, mentre vim.keymap.del consente di rimuoverle.