Die Neovim-Lua-API

Neovim bindet eine LuaJIT-Laufzeitumgebung ein und macht Lua damit neben Vimscript zur nativen Skriptsprache. Plugin-Autoren bevorzugen Lua wegen seiner Geschwindigkeit, seiner echten Datenstrukturen und seines übersichtlichen Modulsystems.

Die globale Tabelle vim ist das Tor zu allem: zum Editorstatus, zur API, zu Optionen und zu Hilfsfunktionen der Standardbibliothek. Sie zu beherrschen, bildet die Grundlage für die moderne Plugin-Entwicklung.

vim.api stellt die API auf niedriger Ebene bereit: jede Funktion trägt das Präfix nvim_. Es handelt sich um dieselben Aufrufe, die externe Clients über RPC verwenden, aber innerhalb des Prozesses werden sie sofort ausgeführt.

Funktionen wie nvim_get_current_buf, nvim_buf_set_lines und nvim_command ermöglichen eine präzise Steuerung. Sie sind stabil, gut dokumentiert und bilden das Rückgrat anspruchsvoller Plugins.

vim.fn stellt eine Verbindung zu den integrierten Funktionen von Vimscript her. Alles, was in Vimscript aufgerufen werden kann, etwa expand() oder fnamemodify(), ist als vim.fn.expand(...) erreichbar.

Das ist besonders wertvoll, wenn noch keine native API existiert. Argumente und Rückgabewerte werden automatisch zwischen Lua- und Vimscript-Typen konvertiert.

Optionen werden über Metatabellen gesetzt. vim.o bezieht sich auf globale Optionen, vim.bo auf bufferlokale und vim.wo auf fensterlokale Optionen.

Eine Zuweisung ist so einfach wie das Schreiben in ein Feld. Damit werden die ausführlichen Aufrufe von nvim_set_option ersetzt, und Konfigurationscode wird besser lesbar.

Mit vim.g lesen und schreiben Sie globale Vim-Variablen. Plugins stellen hier häufig Konfigurationsschalter bereit, etwa vim.g.myplugin_enabled.

Beim Lesen einer nicht gesetzten Variable wird nil zurückgegeben, daher sollten Sie Standardwerte verwenden. Varianten für den Buffer- und Fensterbereich sind als vim.b und vim.w verfügbar.

Verwenden Sie vim.notify, um dem Benutzer Nachrichten anzuzeigen. Die Funktion akzeptiert eine Nachrichtenzeichenkette und optional eine Protokollebene aus vim.log.levels.

Plugin-Manager wie noice oder notify können diese Aufrufe abfangen und eine ansprechendere Benutzeroberfläche bereitstellen. Für Ausgaben an den Benutzer sollten Sie vim.notify gegenüber dem direkten Aufruf von print bevorzugen.

Einige API-Aufrufe sind in schnellen Ereigniskontexten verboten, etwa innerhalb bestimmter Callbacks. vim.schedule verschiebt eine Funktion in die Hauptschleife, in der die vollständige API sicher verwendet werden kann.

So vermeiden Sie die gefürchteten Fehler „E5560“, wenn Sie Buffer aus asynchronen Kontexten oder Autocommand-Kontexten heraus verändern.

nvim_create_autocmd registriert Event-Handler. Gruppieren Sie sie mit nvim_create_augroup und setzen Sie clear = true, um beim Neuladen Duplikate zu vermeiden.

Der Callback erhält eine Event-Tabelle mit Feldern wie buf und match und damit den präzisen Kontext für Ihren Handler.

Neovim wird mit einer umfangreichen Standardbibliothek ausgeliefert. vim.tbl_extend, vim.tbl_keys und vim.split decken häufige Arbeiten mit Tabellen und Zeichenketten ab.

vim.tbl_deep_extend('force', defaults, opts) ist der übliche Weg, um die Benutzerkonfiguration mit den Plugin-Standardwerten zusammenzuführen.

vim.inspect serialisiert jeden Lua-Wert in eine lesbare Zeichenkette, einschließlich verschachtelter Tabellen. Damit lässt sich am schnellsten nachvollziehen, wie API-Rückgabewerte aufgebaut sind.

Kombinieren Sie es mit :lua print(vim.inspect(...)) oder in aktuellen Neovim-Versionen mit :lua= expr, um während der Entwicklung schnell Werte zu untersuchen.

Bevorzugen Sie vim.api für stabile, strukturierte Operationen. Verwenden Sie vim.fn oder vim.cmd als Ausweichmöglichkeit, wenn keine native Funktion existiert.

vim.cmd führt Ex-Befehle als Zeichenketten aus und eignet sich für einmalige Aufrufe wie vim.cmd('highlight ...'). Die Aufrufe lassen sich jedoch schlechter untersuchen als typisierte API-Aufrufe.

Testen Sie Ihr Verständnis der Lua-API von Neovim.

Sie kennen nun die wichtigsten Schnittstellen: vim.api für die typisierte native API, vim.fn für Vimscript-Funktionen und vim.cmd für Ex-Befehle.

Optionen werden über vim.o/bo/wo verwaltet, Variablen über vim.g/b/w, und Hilfsfunktionen wie vim.tbl_deep_extend, vim.notify und vim.schedule vervollständigen das Werkzeugset eines Plugin-Autors.