Написание плагинов Neovim - Руководство для начинающих (Часть I)

Есть много отличных плагинов Neovim, но не так много руководств по написанию плагинов Neovim на Lua. В этой статье давайте приступим к изучению разработки подключаемых модулей Neovim в Lua.

Это руководство для начинающих, и мы собираемся изучить его, разработав простой плагин, и продолжим изучать более сложные темы в будущих статьях.

• Часть 1: Эта статья.
• Часть 2: Доступно здесь.

Оглавление

• Параметры запуска
• Путь выполнения
• Установка пути выполнения
• Использовать специальный файл конфигурации
• Настройка LSP (необязательно)
• Структура каталогов плагинов
• Плагин Hello World
• Определить команду плагина
• "Документация"
• Публикационный плагин
• Установка и тестирование
• Дополнительная литература
• "Резюме"
• "Использованная литература"

Параметры запуска

Давайте сначала рассмотрим различные способы запуска Neovim без загрузки vimrc файлов или подключаемых модулей.

Есть разные способы запустить Neovim без инициализации.

• nvim -u NONE: Запустите Neovim без загрузки vimrc файлов и плагинов.
• nvim -u NORC: Запустите Neovim без загрузки vimrc файлов, но все равно загрузите плагины.
• nvim --noplugin: Запустите Neovim, загрузите vimrc файлы, но не плагины.
• nvim --clean: эквивалент «-u NONE -i NONE». Пропускает инициализацию из файлов и переменных среды. Файл «shada» не читается и не записывается. Исключает каталоги пользователей из «runtimepath».

Чтобы показать вам значение по умолчанию runtimepath, я собираюсь использовать параметр--clean, чтобы запустить Neovim с чистой средой. Введите «:h --clean», чтобы просмотреть документацию.

$ nvim --clean

Runtimepath

Введите :h rtp, чтобы просмотреть документацию по runtimepath.

runtimepath - это список каталогов, в которых выполняется поиск этих файлов времени выполнения. Возможно, вы уже знакомы с некоторыми из этих каталогов.

• autoload: автоматически загружать скрипты (:h autoload-functions)
• colors: файлы цветовой схемы (h :colorscheme)
• compiler: файлы компилятора (:h compiler)
• doc: документация (:h write-local-help)
• ftplugin: плагины для типов файлов (:h write-filetype-plugin)
• pack: пакеты (:h packadd)
• plugin: скрипты плагинов (:h write-plugin)
• syntax: файлы синтаксиса (:h mysyntaxfile)
• lua: файлы Lua. Применимо только для Neovim (:h lua)

Если вы установите какие-либо плагины, вы увидите, что «runtimepath» содержит папки с плагинами.

Чтобы просмотреть runtimepath, вы можете либо

• тип :set rtp?
• используйте регистр выражения. В режиме Insert введите Control-R =, введите &rtp, и runtimepath будет отображаться в текущем буфере.

Установка пути к времени выполнения

Для разработки подключаемых модулей нам необходимо настроить runtimepath так, чтобы он имел текущий каталог разработки. Есть несколько вариантов, которые вы можете настроить.

Запускать

Во время запуска Neovim позволяет передать команду.

$ nvim --cmd "set rtp+=$(pwd)"

Теперь проверьте еще раз runtimepath, и вы сможете увидеть текущую папку.

Использование Vimscript

Кроме того, после запуска Neovim вы можете использовать следующую команду, чтобы установить runtimepath в текущую папку.

:let &runtimepath.=','.escape(expand('%:p:h'), '\,')

Менеджер плагинов

В большинстве случаев вы, вероятно, будете использовать менеджер плагинов, например vim-plug или packer.nvim.

Большинство менеджеров плагинов должны поддерживать локальные плагины и соответственно устанавливать runtimepath. Например.

для vim-plug (фрагмент кода доступен здесь),

" Local plugins
Plug '~/workspace/development/alpha2phi/alpha.nvim'

для packer.nvim,

-- Local plugins can be included
use '~/projects/personal/hover.nvim'

Использовать специальный файл конфигурации

И чтобы использовать конкретный файл конфигурации, вы можете либо

• Используйте опцию $ XDG_CONFIG_HOME во время запуска.

E.g.,

$ XDG_CONFIG_HOME=$HOME/.xdg_home /usr/local/bin/nvim

Базовые (корневые) каталоги соответствуют Спецификации базовых каталогов XDG. В приведенном выше случае Neovim ищет файл конфигурации в папке $HOME/.xdg_home/nvim.

Введите :h $XDG_CONFIG_HOME, чтобы прочитать документацию.

• Используйте параметр -u start-up, чтобы указать на файл конфигурации .vim или .lua .

$ nvim -u /path/to/myconfig.vim
$ nvim -u /path/to/myconfig.lua

Введите :h startup-options, чтобы прочитать документацию.

Настройка LSP (необязательно)

Поскольку мы разрабатываем плагины, имеет смысл настроить LSP для Lua и Vimscript.

Lua

Обратитесь к этой статье, чтобы настроить LSP для Lua.

Vimscript

Для Vimscript мы можем использовать языковой сервер Vim. Инструкции по настройке должны быть похожи на инструкции для других языков, описанные в этой статье.

Структура каталогов плагинов

С runtimepath, настроенным так, чтобы указывать на каталог нашего проекта, давайте создадим эти 3 папки.

• plugin
• lua
• doc

Файлы внутри plugin будут запускаться один раз каждый раз при запуске Neovim. Эти файлы предназначены для содержания кода, который вы всегда хотите загружать при запуске NeoVim. Файлы внутри lua содержат сценарии Lua, а папка doc содержит документацию к вашему плагину.

Для всех возможных каталогов введите :h rtp.

Теперь создайте следующие каталоги и файлы.

• plugin/dev.vim
• plugin/alpha.vim
• lua/hello/init.lua
• lua/hello/helloworld.lua
• doc/alpha.txt

Плагин Hello World

Модуль Hello World

Добавьте следующие строки в lua/hello/helloworld.lua.

local M = {}
function M.sayHelloWorld() print('Hello world!!') end
return M

Это очень простой модуль Lua. Обратитесь сюда, если вы не знакомы с модулем Lua.

Добавьте следующие строки в lua/hello/init.lua

local hello = require('hello.helloworld')
return hello

Введите :h lua-require, чтобы узнать больше о Lua require.

Тестирование

Теперь запустите :lua require(“hello”).sayHelloWorld(), и вы должны увидеть напечатанное «Hello world!!».

Перезагрузка модуля

Теперь измените lua/hello/helloworld.lua. Вместо «Hello world!!» измените его на «Hello world again!!».

Запустите :lua require(“hello”).sayHelloWorld(), и вы все равно увидите «Hello world!!».

Это связано с тем, что модуль «hello» был загружен Neovim и не обновляется после того, как мы внесем изменения.

Теперь добавьте эти строки в plugin/dev.vim

function! ReloadAlpha()
lua << EOF
    for k in pairs(package.loaded) do 
        if k:match("^hello") then
            package.loaded[k] = nil
        end
    end
EOF
endfunction
" Reload the plugin
nnoremap <Leader>pra :call ReloadAlpha()<CR>
" Test the plugin
nnoremap <Leader>ptt :lua require("hello").sayHelloWorld()<CR>

• ReloadAlpha в основном выгружает модуль hello.
• Я также создаю привязки клавиш, чтобы перезагрузить модуль и протестировать плагин.

Теперь либо перезапустите Neovim, либо исходный код dev.vim, запустив :so %.

Нажмите <Leader>pra, а затем <Leader>ptt, и вы должны увидеть последнее изменение.

Определить команду плагина

Добавьте эти строки в plugin/alpha.vim.

if exists('g:loaded_alpha') | finish | endif " prevent loading file twice
let s:save_cpo = &cpo " save user coptions
set cpo&vim           " reset them to defaults
" command to run our plugin
command! AlphaHelloWorld lua require("hello").sayHelloWorld()
let &cpo = s:save_cpo " and restore after
unlet s:save_cpo
let g:loaded_alpha = 1

• Я определяю команду AlphaHelloWorld для вызова нашего hello модуля
• Введите :h cpo, чтобы прочитать документацию по «compatible options».

Документация

Добавьте их в doc/alpha.txt.

Плагин публикации

Опубликовать плагин так же просто, как зафиксировать проект в Github.

plugin/dev.vim предназначен только для разработки. Вы можете исключить этот файл из фиксации, включив его в .gitignore.

Установка и тестирование

Теперь используйте ваш любимый менеджер плагинов, чтобы установить плагин.

Например, используя vim-plug,

Plug 'alpha2phi/alpha.nvim'

• Запустите «:PlugInstall», чтобы установить плагин.
• Введите «:AlphaHelloWorld», и сообщение «Hello world» будет напечатано.
• Введите «:h alpha.nvim» или «:h AlphaHelloWorld», и вы увидите справочную документацию.

Дополнительная литература

• Введите :h lua, чтобы прочитать введение в Lua.
• Гид Neovim Lua.

Резюме

Теперь у нас есть «hello world» версия нашего плагина. В следующей статье продолжим улучшать плагин.

Исходный код плагина можно найти в этом репозитории.

использованная литература

• Трудный путь изучения Vimscript
• YouTube: Vim как IDE
• YouTube: Vim: Учебное пособие по настройке и настройке
• YouTube - Создайте простой плагин для Vim / Neovim с нуля: cyclist.vim
• YouTube - Написание плагинов для Neovim
• YouTube - Руководство по разработке плагина Neovim
• Lua - разорено

Если вы еще не являетесь участником Medium и хотите им стать, нажмите здесь. (Часть вашей абонентской платы будет использована для поддержки alpha2phi.)