L’API Lua de Neovim

Neovim intègre un environnement d’exécution LuaJIT, ce qui fait de Lua le langage de script natif aux côtés de Vimscript. Les auteurs d’extensions préfèrent Lua pour sa rapidité, ses véritables structures de données et son système de modules clair.

La table globale vim donne accès à tout : l’état de l’éditeur, l’API, les options et les fonctions auxiliaires de la bibliothèque standard. La maîtriser constitue le fondement du développement moderne d’extensions.

vim.api expose l’API distante de bas niveau : toutes les fonctions préfixées par nvim_. Ce sont les mêmes appels que ceux utilisés par les clients externes via RPC, mais ils s’exécutent instantanément au sein du processus.

Des fonctions comme nvim_get_current_buf, nvim_buf_set_lines et nvim_command offrent un contrôle précis. Elles sont stables, bien documentées et constituent le socle des extensions sérieuses.

vim.fn fait le lien avec les fonctions intégrées de Vimscript. Toute fonction appelable dans Vimscript, comme expand() ou fnamemodify(), est accessible sous la forme vim.fn.expand(...).

C’est particulièrement utile lorsqu’aucune API native n’existe encore. Les arguments et les valeurs de retour sont automatiquement convertis entre les types Lua et Vimscript.

Les options sont définies au moyen de métatables. vim.o cible les options globales, vim.bo celles propres au tampon et vim.wo celles propres à la fenêtre.

Une simple affectation de champ suffit. Cela remplace les appels verbeux à nvim_set_option et se lit naturellement dans le code de configuration.

vim.g lit et écrit les variables globales de Vim. Les extensions y exposent souvent des options de configuration, comme vim.g.myplugin_enabled.

La lecture d’une variable non définie renvoie nil ; prévoyez donc des valeurs par défaut. Des variantes propres au tampon et à la fenêtre existent sous la forme de vim.b et vim.w.

Utilisez vim.notify pour afficher des messages à l’utilisateur. Cette fonction accepte une chaîne de message et un niveau de journalisation facultatif provenant de vim.log.levels.

Les gestionnaires d’extensions comme noice ou notify peuvent intercepter ces messages pour offrir une interface plus agréable. Préférez vim.notify à l’affichage brut avec print pour les messages destinés à l’utilisateur.

Certains appels d’API sont interdits dans les contextes d’événements rapides, notamment à l’intérieur de certains rappels. vim.schedule reporte une fonction dans la boucle principale, où l’ensemble de l’API peut être utilisé sans risque.

Cela évite les erreurs redoutées E5560 lors de la modification de tampons depuis des contextes asynchrones ou de commandes automatiques.

nvim_create_autocmd enregistre des gestionnaires d’événements. Regroupez-les avec nvim_create_augroup et définissez clear = true pour éviter les doublons lors d’un rechargement.

Le rappel reçoit une table d’événement contenant des champs comme buf et match, ce qui fournit au gestionnaire un contexte précis.

Neovim fournit une riche bibliothèque standard. vim.tbl_extend, vim.tbl_keys et vim.split couvrent les manipulations courantes des tables et des chaînes.

vim.tbl_deep_extend('force', defaults, opts) est la méthode de référence pour fusionner la configuration de l’utilisateur avec les valeurs par défaut de l’extension.

vim.inspect sérialise toute valeur Lua en une chaîne lisible, y compris les tables imbriquées. C’est le moyen le plus rapide de comprendre la forme des valeurs renvoyées par l’API.

Associez-le à :lua print(vim.inspect(...)) ou à :lua= expr dans les versions récentes de Neovim pour effectuer rapidement une inspection pendant le développement.

Préférez vim.api pour les opérations structurées et stables. Utilisez vim.fn ou vim.cmd comme solution de repli lorsqu’aucune fonction native n’existe.

vim.cmd exécute des commandes Ex sous forme de chaînes et convient aux opérations ponctuelles comme vim.cmd('highlight ...'), mais permet moins facilement l’introspection que les appels d’API typés.

Testez votre compréhension de l’API Lua de Neovim.

Vous connaissez maintenant les principales interfaces : vim.api pour l’API native typée, vim.fn pour les fonctions Vimscript et vim.cmd pour les commandes Ex.

Les options passent par vim.o/bo/wo, les variables par vim.g/b/w, et des fonctions auxiliaires comme vim.tbl_deep_extend, vim.notify et vim.schedule complètent la boîte à outils de l’auteur d’extension.