Neovim Lua API
プラグインがどのように連携するかを学びます。
「Neovim Lua API」はCoddyKit上の無料Lua Academyレッスンです。 これはレッスン1/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはLua Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Lua Academyコースには全4レッスンが含まれています。
NeovimでLuaを使う理由
NeovimはLuaJITランタイムを組み込んでいるため、Vimscriptと並ぶネイティブのスクリプト言語としてLuaを利用できます。プラグイン作成者がLuaを好むのは、高速で、実際のデータ構造を扱え、モジュールシステムも簡潔だからです。
グローバルなvimテーブルは、エディターの状態、API、オプション、標準ライブラリのヘルパーなど、あらゆる機能への入り口です。これを使いこなすことが、現代的なプラグイン開発の基礎になります。
print(vim.inspect(vim.version()))vim.apiレイヤー
vim.apiは低レベルのリモートAPIを公開しています。すべての関数名にはnvim_が接頭辞として付きます。これらは外部クライアントがRPC経由で使用するものと同じ呼び出しですが、プロセス内では即座に実行されます。
nvim_get_current_buf、nvim_buf_set_lines、nvim_commandなどの関数を使うと、対象を正確に制御できます。これらは安定していてドキュメントも充実しており、本格的なプラグインの基盤となります。
local buf = vim.api.nvim_get_current_buf()
local name = vim.api.nvim_buf_get_name(buf)
print(name)vim.fn — Vimscript関数の呼び出し
vim.fnはVimscriptの組み込み関数への橋渡しをします。expand()やfnamemodify()など、Vimscriptで呼び出せる関数はすべてvim.fn.expand(...)の形で利用できます。
ネイティブAPIがまだ存在しない場合に、これは非常に役立ちます。引数と戻り値は、Luaの型とVimscriptの型の間で自動的に変換されます。
local path = vim.fn.expand('%:p')
local tail = vim.fn.fnamemodify(path, ':t')
print(tail)オプション: vim.o、vim.bo、vim.wo
オプションはメタテーブルを通じて設定します。vim.oはグローバルオプション、vim.boはバッファローカルオプション、vim.woはウィンドウローカルオプションを対象とします。
設定はフィールドに値を書き込むだけで行えます。これにより、冗長なnvim_set_optionの呼び出しを置き換えられ、設定コードを自然に記述できます。
vim.o.number = true
vim.bo.shiftwidth = 2
vim.wo.wrap = falsevim.gとグローバル変数
vim.gはグローバルなVim変数を読み書きします。プラグインでは、vim.g.myplugin_enabledのように、設定の切り替えをここで公開することがよくあります。
設定されていない変数を読み取るとnilが返るため、デフォルト値で保護してください。バッファスコープとウィンドウスコープの対応物として、vim.bとvim.wもあります。
vim.g.mapleader = ' '
local enabled = vim.g.myplugin_enabled or false
print(enabled)通知とエコー
ユーザーにメッセージを表示するにはvim.notifyを使用します。メッセージ文字列と、vim.log.levelsにある任意のログレベルを受け取ります。
noiceやnotifyなどのプラグインマネージャーは、これらの通知を受け取って、より使いやすいUIにできます。ユーザー向けの出力には、通常のprintよりもvim.notifyを優先してください。
vim.notify('Plugin loaded', vim.log.levels.INFO)
vim.notify('Missing config', vim.log.levels.WARN)vim.scheduleによるスケジューリング
特定のコールバック内など、高速イベントコンテキストでは一部のAPI呼び出しが禁止されています。vim.scheduleを使うと、完全なAPIを安全に利用できるメインループに関数の実行を延期できます。
これにより、非同期処理や自動コマンドのコンテキストからバッファを変更したときに発生する、悩ましい「E5560」エラーを回避できます。
vim.schedule(function()
vim.api.nvim_buf_set_lines(0, 0, 0, false, {'Hello'})
end)Luaでの自動コマンド
nvim_create_autocmdはイベントハンドラーを登録します。nvim_create_augroupでグループ化し、再読み込み時の重複を避けるためにclear = trueを設定してください。
コールバックには、bufやmatchなどのフィールドを持つイベントテーブルが渡されるため、ハンドラーの対象を正確に把握できます。
local grp = vim.api.nvim_create_augroup('MyGrp', { clear = true })
vim.api.nvim_create_autocmd('BufWritePost', {
group = grp,
pattern = '*.lua',
callback = function(ev) print('saved ' .. ev.file) end,
})vim.tblと文字列ヘルパー
Neovimには充実した標準ライブラリが用意されています。vim.tbl_extend、vim.tbl_keys、vim.splitを使えば、テーブルや文字列に関する一般的な処理を行えます。
vim.tbl_deep_extend('force', defaults, opts)は、ユーザー設定をプラグインのデフォルト設定にマージする標準的な方法です。
local defaults = { width = 40, border = 'single' }
local opts = { width = 60 }
local cfg = vim.tbl_deep_extend('force', defaults, opts)
print(cfg.width, cfg.border)デバッグのためのvim.inspect
vim.inspectは、ネストしたテーブルを含むあらゆるLua値を、読みやすい文字列にシリアライズします。APIが返す値の形を把握する最も手早い方法です。
開発中にすばやく確認するには、:lua print(vim.inspect(...))や、最近のNeovimで使える:lua= exprと組み合わせてください。
local info = vim.api.nvim_get_mode()
print(vim.inspect(info))APIとVimscriptの使い分け
安定した構造化操作にはvim.apiを優先してください。ネイティブ関数がない場合はvim.fnまたはvim.cmdを使用します。
vim.cmdは文字列としてexコマンドを実行するため、vim.cmd('highlight ...')のような一度きりの処理に便利ですが、型付きのAPI呼び出しほど内部の状態を調べやすくはありません。
vim.cmd('syntax on')
vim.cmd.colorscheme('habamax')クイックチェック
NeovimのLua APIの全体像について理解度を確認してください。
復習: Lua API
これで、主なAPI層を理解できました。型付きのネイティブAPIにはvim.api、Vimscript関数にはvim.fn、exコマンドにはvim.cmdを使用します。
オプションはvim.o/bo/wo、変数はvim.g/b/wを通じて扱い、vim.tbl_deep_extend、vim.notify、vim.scheduleなどのヘルパーがプラグイン作成者のツールキットを補完します。
よくある質問
「Neovim Lua API」レッスンは無料ですか？
はい。「Neovim Lua API」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Lua Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Lua Academyコースには全4レッスンが含まれています。
「Neovim Lua API」で何を学びますか？
プラグインがどのように連携するかを学びます。 ブラウザで直接実行するハンズオンコードでLua Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Lua Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのLua Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン1/4です。
「Neovim Lua API」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このLua Academyレッスンでコードを書いて実行できますか？
はい。すべてのLua Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- Neovim Lua API
- コマンドとキーマップ
- バッファーとウィンドウ
- プラグインをパッケージ化する