API Lua Neovima

Neovim zawiera środowisko uruchomieniowe LuaJIT, dzięki czemu Lua jest natywnym językiem skryptowym obok Vimscript. Autorzy wtyczek preferują Lua ze względu na szybkość, rzeczywiste struktury danych i przejrzysty system modułów.

Globalna tabela vim jest bramą do wszystkiego: stanu edytora, API, opcji i pomocniczych funkcji biblioteki standardowej. Jej opanowanie stanowi podstawę nowoczesnego tworzenia wtyczek.

vim.api udostępnia niskopoziomowe zdalne API: każdą funkcję z prefiksem nvim_. Są to te same wywołania, których zewnętrzni klienci używają przez RPC, ale w obrębie procesu wykonują się natychmiast.

Funkcje takie jak nvim_get_current_buf, nvim_buf_set_lines i nvim_command zapewniają precyzyjną kontrolę. Są stabilne, dobrze udokumentowane i stanowią podstawę zaawansowanych wtyczek.

vim.fn łączy Lua z wbudowanymi funkcjami Vimscript. Wszystko, co można wywołać w Vimscript, na przykład expand() lub fnamemodify(), jest dostępne jako vim.fn.expand(...).

Jest to niezwykle przydatne, gdy nie istnieje jeszcze natywne API. Argumenty i wartości zwracane są automatycznie konwertowane między typami Lua i Vimscript.

Opcje ustawia się za pomocą metatabel. vim.o dotyczy opcji globalnych, vim.bo opcji lokalnych dla bufora, a vim.wo opcji lokalnych dla okna.

Przypisanie jest tak proste jak zapis do pola. Zastępuje to rozwlekłe wywołania nvim_set_option i dobrze pasuje do kodu konfiguracyjnego.

vim.g odczytuje i zapisuje globalne zmienne Vima. Wtyczki często udostępniają tutaj przełączniki konfiguracji, na przykład vim.g.myplugin_enabled.

Odczyt nieustawionej zmiennej zwraca nil, dlatego należy stosować wartości domyślne. Istnieją także warianty o zasięgu bufora i okna: vim.b oraz vim.w.

Należy używać vim.notify, aby wyświetlać użytkownikowi komunikaty. Funkcja przyjmuje ciąg komunikatu oraz opcjonalny poziom logowania z vim.log.levels.

Menedżery wtyczek, takie jak noice lub notify, mogą przechwytywać te komunikaty i prezentować je w atrakcyjniejszym interfejsie. W przypadku komunikatów dla użytkownika należy preferować vim.notify zamiast surowego print.

Niektóre wywołania API są zabronione w kontekstach szybkich zdarzeń, na przykład wewnątrz określonych callbacków. vim.schedule odracza wykonanie funkcji do głównej pętli, w której całe API jest bezpieczne.

Pozwala to uniknąć budzących grozę błędów „E5560” podczas modyfikowania buforów w kontekstach asynchronicznych lub autokomend.

nvim_create_autocmd rejestruje procedury obsługi zdarzeń. Należy grupować je za pomocą nvim_create_augroup i ustawić clear = true, aby uniknąć duplikatów po przeładowaniu.

Callback otrzymuje tabelę zdarzenia z polami takimi jak buf i match, co zapewnia precyzyjny kontekst dla procedury obsługi.

Neovim udostępnia bogatą bibliotekę standardową. Funkcje vim.tbl_extend, vim.tbl_keys i vim.split obejmują typowe operacje na tabelach i łańcuchach znaków.

vim.tbl_deep_extend('force', defaults, opts) to kanoniczny sposób scalania konfiguracji użytkownika z domyślnymi ustawieniami wtyczki, tak aby konfiguracja użytkownika je nadpisywała.

vim.inspect serializuje dowolną wartość Lua do czytelnego ciągu znaków, w tym zagnieżdżone tabele. To najszybszy sposób na zrozumienie struktur wartości zwracanych przez API.

Podczas tworzenia można połączyć ją z :lua print(vim.inspect(...)) albo użyć :lua= expr w nowszych wersjach Neovim, aby szybko przeprowadzić inspekcję.

Należy preferować vim.api w przypadku stabilnych, ustrukturyzowanych operacji. Gdy nie istnieje natywna funkcja, należy użyć vim.fn lub vim.cmd.

vim.cmd wykonuje polecenia ex jako ciągi znaków i przydaje się w jednorazowych przypadkach, takich jak vim.cmd('highlight ...'), ale zapewnia mniej możliwości introspekcji niż typowane wywołania API.

Znają już Państwo podstawowe warstwy: vim.api jako typowane natywne API, vim.fn do funkcji Vimscript oraz vim.cmd do poleceń ex.

Opcje obsługuje się przez vim.o/bo/wo, zmienne przez vim.g/b/w, a funkcje pomocnicze, takie jak vim.tbl_deep_extend, vim.notify i vim.schedule, uzupełniają zestaw narzędzi autora wtyczki.