Repository: willelz/nvim-lua-guide-ja Branch: master Commit: cb52e8f92577 Files: 9 Total size: 189.7 KB Directory structure: gitextract_vu8rkx56/ ├── .gitattributes ├── README.ja.md ├── README.md ├── doc/ │ ├── nvim-lua-guide.jax │ └── nvim-lua-guide.txt └── scripts/ ├── docgen.sh ├── sections_tags.awk ├── to_vimdoc.sed └── to_vimdocja.sed ================================================ FILE CONTENTS ================================================ ================================================ FILE: .gitattributes ================================================ scripts/* -linguist-detectable ================================================ FILE: README.ja.md ================================================ :arrow_upper_left: (迷子になった？ GitHub TOCを使いましょう！) **:warning: :warning: :warning: このガイドの最新版は、Neovimのドキュメントにあります。 [`:help lua-guide`](https://neovim.io/doc/user/lua-guide.html#lua-guide)を参照してください。 :warning: :warning: :warning:** 日本語はこちら→https://github.com/willelz/neovimdoc-ja/blob/main/doc/lua-guide.jax # Getting started using Lua in Neovim ## はじめに Neovimの[ファーストクラス言語](https://github.com/neovim/neovim/wiki/FAQ#why-embed-lua-instead-of-x)としての[Lua](https://www.youtube.com/watch?v=IP3J56sKtn0)はキラー機能の1つになりつつあります。 しかし、Luaでプラグインを書くための教材はVim script程多くありません。これは、Luaを始めるための基本的な情報を提供する試みです。 このガイドは少なくともNeovim 0.5を使用していることを前提としています。 ### Luaを学ぶ まだLuaについて詳しくない場合、学ぶためのリソースはたくさんあります。: - [Learn X in Y minutes page about Lua](https://learnxinyminutes.com/docs/lua/)は基本的な概要を説明します。 - [このガイド](https://github.com/medwatt/Notes/blob/main/Lua/Lua_Quick_Guide.ipynb)も素早く始めるのに良いチュートリアルです。 - 動画が好きなら、Derek Banasの動画があります。[1-hour tutorial on the language](https://www.youtube.com/watch?v=iMacxZQMPXs) - 実行できるサンプルを使い、対話的に学びたいですか？[LuaScript tutorial](https://www.luascript.dev/learn)を試してみてください。 - [lua-users wiki](http://lua-users.org/wiki/LuaDirectory)にはLua関連のトピックごとの便利な情報がたくさんあります。 - [official reference manual for Lua](https://www.lua.org/manual/5.1/)には最も包括的な情報があります。(エディタで快適に読みたいなら、Vimdocプラグインがあります。:[milisims/nvim-luaref](https://github.com/milisims/nvim-luaref)) Luaはとてもクリーンでシンプルな言語であることに注意してください。JavaScriptのようなスクリプト言語の経験があれば、学ぶことは簡単です。あなたはもう自分で思っているよりLuaについて知っているかもしれません！ Note: Neovimに埋め込まれているLuaは[LuaJIT](https://staff.fnwi.uva.nl/h.vandermeer/docs/lua/luajit/luajit_intro.html) 2.1.0でLua 5.1と互換性を維持しています。 ### Luaを書くための既存のチュートリアル Luaでプラグインを書くためのチュートリアルが既にいくつかあります。それらはこのガイドを書くのに役に立ちました。筆者に感謝します。 - [teukka.tech - init.vimからinit.luaへ](https://teukka.tech/luanvim.html) - [dev.to - プラグインをLuaで書く方法](https://dev.to/2nit/how-to-write-neovim-plugins-in-lua-5cca) - [dev.to - プラグインのUIをLuaで作る方法](https://dev.to/2nit/how-to-make-ui-for-neovim-plugins-in-lua-3b6e) - [ms-jpq - Neovim Async Tutorial](https://github.com/ms-jpq/neovim-async-tutorial) - [oroques.dev - Neovim 0.5の機能とinit.luaへの切り替え](https://oroques.dev/notes/neovim-init/) - [ゼロからステータスラインを作る - jdhao's blog](https://jdhao.github.io/2019/11/03/vim_custom_statusline/) - [LuaでNeovimを設定する](https://icyphox.sh/blog/nvim-lua/) - [Devlog | Luaで設定するために知る必要のあること](https://vonheikemen.github.io/devlog/tools/configuring-neovim-using-lua/) ### 関連するプラグイン - [Vimpeccable](https://github.com/svermeulen/vimpeccable) - .vimrc内でLuaを書くのに役に立つプラグイン - [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) - 二度書きたくないLua関数のすべて - [popup.nvim](https://github.com/nvim-lua/popup.nvim) - vimのPopup APIのNeovimでの実装 - [nvim_utils](https://github.com/norcalli/nvim_utils) - [nvim-luadev](https://github.com/bfredl/nvim-luadev) - REPL/debugコンソール - [nvim-luapad](https://github.com/rafcamlet/nvim-luapad) - 組込みLuaエンジンのインタラクティブなリアルタイムスクラッチパッド - [nlua.nvim](https://github.com/tjdevries/nlua.nvim) - NeovimのLua開発 - [BetterLua.vim](https://github.com/euclidianAce/BetterLua.vim) - Vim/Neovimより良いシンタックスハイライト ## Luaファイルを置く場所 ### init.lua Neovimは、`init.vim`の代わりに設定ファイルとして`init.lua`を読み込むことをサポートしています。 Note: `init.lua`は _完全に_ オプションです。`init.vim`は廃止されず、設定として有効です。 いくつかの機能は、まだ100%Luaに公開されていないので注意してください。 参照: - [`:help config`](https://neovim.io/doc/user/starting.html#config) ### モジュール Luaモジュールは、`runtimepath`内の`lua/`フォルダにあります(ほとんどの場合、\*nixでは`~/.config/nvim/lua`、Windowsでは`~/AppData/Local/nvim/lua`を意味します)。 このフォルダにあるファイルをLuaモジュールとして`require()`できます。 例として次のフォルダ構造を取り上げましょう。: ```text 📂 ~/.config/nvim ├── 📁 after ├── 📁 ftplugin ├── 📂 lua │ ├── 🌑 myluamodule.lua │ └── 📂 other_modules │ ├── 🌑 anothermodule.lua │ └── 🌑 init.lua ├── 📁 pack ├── 📁 plugin ├── 📁 syntax └── 🇻 init.vim ``` 次のLuaコードは`myluamodule.lua`をロードします。: ```lua require('myluamodule') ``` `.lua`拡張子がないことに注意してください。 同様に、`other_modules/anothermodule.lua` のロードは次のように行います。: ```lua require('other_modules.anothermodule') -- or require('other_modules/anothermodule') ``` パスの区切りはドット`.`またはスラッシュ`/`で示されます。 フォルダに`init.lua`が含まれている場合、ファイル名を指定せずにロードできます。 ```lua require('other_modules') -- other_modules/init.luaをロード ``` 存在しないモジュール、構文エラーを含むモジュールをrequireすると実行中のスクリプトは停止します。 エラーを防ぐために、`pcall()`を使用できます。 ```lua local ok, _ = pcall(require, 'module_with_error') if not ok then -- not loaded end ``` 参照: - [`:help lua-require`](https://neovim.io/doc/user/lua.html#lua-require) #### Tips いくつかのLuaプラグインは`lua/`フォルダ内に同じ名前のファイルがあるかもしれません。これにより、名前空間の衝突を起こす可能性があります。 異なる2つのプラグインに`lua/main.lua`がある場合、`require('main')`は曖昧です。: どのファイルを読み込みますか？ トップレベルのフォルダで名前空間をつけることをお勧めします。: `lua/plugin_name/main.lua` #### Runtime files Vim scriptと同様に、`runtimepath`内にある特定のフォルダからLuaファイルを自動的に読み込めます。 現在、次のフォルダがサポートされています。: - `colors/` - `compiler/` - `ftplugin/` - `ftdetect/` - `indent/` - `plugin/` - `syntax/` Note: runtimeデイレクトリでは、すべての`*.vim`ファイルは`*.lua`ファイルの前に読み込まれます。 参照: - [`:help 'runtimepath'`](https://neovim.io/doc/user/options.html#'runtimepath') - [`:help load-plugins`](https://neovim.io/doc/user/starting.html#load-plugins) #### Tips ランタイムファイルはLuaのモジュールシステムをベースとしていないため、2つのプラグインは`plugin/main.lua`を問題なく持つことができます。 ## Vim scriptからLuaを使用する ### :lua Luaのチャンクを実行します。 ```vim :lua require('myluamodule') ``` ヒアドキュメント構文を使用すると複数行に書くことができます。: ```vim echo "Here's a bigger chunk of Lua code" lua << EOF local mod = require('mymodule') local tbl = {1, 2, 3} for k, v in ipairs(tbl) do mod.method(v) end print(tbl) EOF ``` Note: 各`:lua`コマンドは独自のスコープを持っており、`local`を付けた変数はコマンドの外からアクセスできません。 次の例は動作しません。: ```vim :lua local foo = 1 :lua print(foo) " '1'ではなく'nil'が出力されます。 ``` Note 2: Luaの`print()`は`:echomsg`と同じように動作します。出力はメッセージ履歴に保存されます。また、`:silent`で抑制できます。 参照: - [`:help :lua`](https://neovim.io/doc/user/lua.html#Lua) - [`:help :lua-heredoc`](https://neovim.io/doc/user/lua.html#:lua-heredoc) ### :luado このコマンドはカレントバッファの範囲行にLuaチャンクを実行します。範囲を指定しない場合、バッファ全体に作用します。 チャンクから`return`された文字列は、各行を置き換えるために使用されます。 次のコマンドは、カレントバッファのすべての行を`hello world`に置き換えます。: ```vim :luado return 'hello world' ``` 2つの暗黙的な変数`line`と`liner`が提供されます。`line`は対象行のテキストで、`liner`はその行数です。 次のコマンドは、すべての偶数行のテキストを大文字にします。 ```vim :luado if linenr % 2 == 0 then return line:upper() end ``` 参照: - [`:help :luado`](https://neovim.io/doc/user/lua.html#:luado) ### Luaファイルの読み込み NeovimはLuaファイルを読み込むためのEXコマンドを3つ提供しています。 - `:luafile` - `:source` - `:runtime` `:luafile`と`:source`はとてもよく似ています。: ```vim :luafile ~/foo/bar/baz/myluafile.lua :luafile % :source ~/foo/bar/baz/myluafile.lua :source % ``` `:source`は範囲指定もサポートしており、スクリプトの一部を実行するのに役立ちます。: ```vim :1,10source ``` `:runtime`は少し異なります。: `'runtimepath'`オプションで読み込むファイルを指定します。 詳細は[`:help :runtime`](https://neovim.io/doc/user/repeat.html#:runtime)を参照してください。 参照: - [`:help :luafile`](https://neovim.io/doc/user/lua.html#:luafile) - [`:help :source`](https://neovim.io/doc/user/repeat.html#:source) - [`:help :runtime`](https://neovim.io/doc/user/repeat.html#:runtime) #### Sourcing a lua file vs calling require(): `require()`関数を呼ぶこととLuaファイルの読み込みの違いは何か、どちらを使うべきかを疑問に思うかもしれません。 それらには異なるユースケースがあります。: - `require()`: - Luaの組込み関数です。Luaのモジュールを読み込むのに使用します。 - `'runtimepath'`内にある`lua/`フォルダからモジュールを探します。 - どのモジュールをロードしたかを記憶し、多重に実行されるのを防ぎます。Neovim実行中に、モジュールに含まれるコードを変更し、もう一度`require()`を実行してもモジュールは更新されません。 - `:luafile`, `:source`, `runtime`: - Exコマンドです。モジュールには対応していません。 - 以前に実行されたかどうかに関わらず実行されます。 - `:luafile`と`:source`は現在のウィンドウのディレクトリに対して相対パス・絶対パスを取ります。 - `runtime`は、`'rutimepath'`オプションを使用してファイルを探します。 `:source`や`:runtime`、ランタイムディレクトリから自動的に読み込まれたファイルも`scriptnames`と`--startuptime`に表示されます。 ### luaeval() Vim scriptの組込み関数です。文字列のLua式を評価して返します。 Luaの型は自動的にVim scriptの型に変換されます。(その逆も同様です。) ```vim " 変数に結果を代入することができます。 let variable = luaeval('1 + 1') echo variable " 2 let concat = luaeval('"Lua".." is ".."awesome"') echo concat " 'Lua is awesome' " リストのようなテーブルはVimのリストに変換されます。 let list = luaeval('{1, 2, 3, 4}') echo list[0] " 1 echo list[1] " 2 " 注意 Luaのテーブルと違い、Vimのリストは0インデックスです。 " 辞書のようなテーブルはVimの辞書に変換されます。 let dict = luaeval('{foo = "bar", baz = "qux"}') echo dict.foo " 'bar' " bool値とnilも同様です。 echo luaeval('true') " v:true echo luaeval('nil') " v:null " Lua関数のエイリアスをVim scriptで作ることができます。 let LuaMathPow = luaeval('math.pow') echo LuaMathPow(2, 2) " 4 let LuaModuleFunction = luaeval('require("mymodule").myfunction') call LuaModuleFunction() " Vimの関数にLuaの関数を値として渡すこともできます。 lua X = function(k, v) return string.format("%s:%s", k, v) end echo map([1, 2, 3], luaeval("X")) ``` `luaeval()`は式にデータを渡すことのできる任意の2つ目の引数があります。Luaからは`_A`としてアクセスできます。 ```vim echo luaeval('_A[1] + _A[2]', [1, 1]) " 2 echo luaeval('string.format("Lua is %s", _A)', 'awesome') " 'Lua is awesome' ``` 参照: - [`:help luaeval()`](https://neovim.io/doc/user/lua.html#luaeval()) ### v:lua Vimのグローバル変数です。Vim scriptからLuaのグローバル名前空間([`_G`](https://www.lua.org/manual/5.1/manual.html#pdf-_G)) 内の関数を直接呼ぶことができます。 この場合でも、Vim scriptの型はLuaの型に変換されます。逆も同様です。 ```vim call v:lua.print('Hello from Lua!') " 'Hello from Lua!' let scream = v:lua.string.rep('A', 10) echo scream " 'AAAAAAAAAA' " How about a nice statusline? lua << EOF function _G.statusline() local filepath = '%f' local align_section = '%=' local percentage_through_file = '%p%%' return string.format( '%s%s%s', filepath, align_section, percentage_through_file ) end EOF set statusline=%!v:lua.statusline() " Also works in expression mappings lua << EOF function _G.check_back_space() local col = vim.api.nvim_win_get_cursor(0)[2] return (col == 0 or vim.api.nvim_get_current_line():sub(col, col):match('%s')) and true end EOF inoremap \ pumvisible() ? "\" : \ v:lua.check_back_space() ? "\" : \ completion#trigger_completion() " シングルクォートを使用したり、括弧を省略して、Luaモジュールから関数を呼び出します: call v:lua.require'module'.foo() ``` 参照: - [`:help v:lua`](https://neovim.io/doc/user/eval.html#v:lua) - [`:help v:lua-call`](https://neovim.io/doc/user/lua.html#v:lua-call) #### 警告 この変数は関数呼び出しにのみ使用できます。次の例はエラーになります。: ```vim " 関数のエイリアスは動作しません let LuaPrint = v:lua.print " 辞書アクセスは動作しません echo v:lua.some_global_dict['key'] " 関数を値として使用できません echo map([1, 2, 3], v:lua.global_callback) ``` ### Tips 設定ファイルに、`let g:vimsyn_embed = 'l'`を追加すると.vimファイル内のLuaを構文ハイライトできます。 詳細は[`:help g:vimsyn_embed`](https://neovim.io/doc/user/syntax.html#g:vimsyn_embed)を参照してください。 ## vim名前空間 NeovimはLuaからAPIを使うためのエントリーポイントとして、`vim`グローバル変数を公開しています。 これは、拡張された標準ライブラリやさまざまなサブモジュールを提供します。 いくつかの注目すべき関数とモジュール: - `vim.inspect`: Luaオブジェクトを人間が読みやすい文字列に変換する(テーブルを調べるのに便利です。) - `vim.regex`: LuaからVimの正規表現を使う - `vim.api`: API関数を公開するモジュール(リモートプラグインで使うAPIと同じです) - `vim.ui`: プラグインから利用できる上書き可能な関数 - `vim.loop`: Neovimのイベントループ機能を公開するモジュール(LibUVを使います) - `vim.lsp`: 組込みのLSPクライアントを操作するモジュール - `vim.treesitter`: tree-sitterライブラリの機能を公開するモジュール このリストは決して包括的なリストではありません。`vim`変数で何かできるかを詳しく知りたい場合は、[`:help lua-stdlib`](https://neovim.io/doc/user/lua.html#lua-stdlib)と[`:help lua-vim`](https://neovim.io/doc/user/lua.html#lua-vim)が最適です。 または、`:lua print(vim.inspect(vim))`を実行してすべてのモジュールのリストを取得できます。 API関数は、[`:help api-global`](https://neovim.io/doc/user/api.html#api-global)にあります。 #### Tips オブジェクトの中身を検査するのに毎回`print(vim.inspect(x))`を書くのは面倒です。設定にグローバルなラッパー関数を含めることは価値があるかもしれません。(Neovim 0.7.0+では、この関数は組込み関数です。参照 [`:help vim.pretty_print()`](https://neovim.io/doc/user/lua.html#vim.pretty_print())): ```lua function _G.put(...) local objects = {} for i = 1, select('#', ...) do local v = select(i, ...) table.insert(objects, vim.inspect(v)) end print(table.concat(objects, '\n')) return ... end ``` コードまたはコマンドラインからとても早くオブジェクトの中身を検査できます。 ```lua put({1, 2, 3}) ``` ```vim :lua put(vim.loop) ``` または、`:lua`コマンドでLua式の前に `=` をつけて、整列させて表示できます。(Neovim 0.7+のみ) ```vim :lua =vim.loop ``` 加えて、他の言語と比較して組込みのLua関数が不足している場合があります(例えば、`os.clock`はミリ秒ではなく秒数のみを返します)。 必ず、Neovim stdlib(それと`vim.fn`。詳しくは後述します。)を見てください。おそらく、探しものはそこにあります。 ## LuaからVim scriptを使用する ### vim.api.nvim_eval() 文字列で与えられたVim scriptの式を評価してその値を返します。Vim scriptの型は自動的にLuaの型に変換されます。(その逆も同様です。) これは、Vim scriptの`luaeval()`と同様です。 ```lua -- 型は正しく変換されます。 print(vim.api.nvim_eval('1 + 1')) -- 2 print(vim.inspect(vim.api.nvim_eval('[1, 2, 3]'))) -- { 1, 2, 3 } print(vim.inspect(vim.api.nvim_eval('{"foo": "bar", "baz": "qux"}'))) -- { baz = "qux", foo = "bar" } print(vim.api.nvim_eval('v:true')) -- true print(vim.api.nvim_eval('v:null')) -- nil ``` #### 警告 `luaeval()`と違い、式にデータを渡すための暗黙的な変数`_A`を提供しません。 ### vim.api.nvim_exec() Vim scriptのチャンクを実行します。実行するソースコートを含む文字列と、コードの出力を返すかどうかを決めるbool値を受け取ります(例えば、出力を変数に格納できます)。 ```lua local result = vim.api.nvim_exec( [[ let s:mytext = 'hello world' function! s:MyFunction(text) echo a:text endfunction call s:MyFunction(mytext) ]], true) print(result) -- 'hello world' ``` #### 警告 Neovim 0.6.0より前のバージョンでは 、`nvim_exec` はスクリプトローカル変数(`s:`)をサポートしていません。 ### vim.api.nvim_command() Exコマンドを実行します。実行するコマンドを含む文字列を受け取ります。 ```lua vim.api.nvim_command('new') vim.api.nvim_command('wincmd H') vim.api.nvim_command('set nonumber') vim.api.nvim_command('%s/foo/bar/g') ``` ### vim.cmd() `vim.api.nvim_exec()`のエイリアスです。コマンドの引数のみを必要とし、`output`は常に`false`に設定されます。 ```lua vim.cmd('buffers') vim.cmd([[ let g:multiline_list = [ \ 1, \ 2, \ 3, \ ] echo g:multiline_list ]]) ``` #### Tips これらの関数は文字列を渡すため、多くの場合、バックスラッシュをエスケープする必要があります。: ```lua vim.cmd('%s/\\Vfoo/bar/g') ``` 二重括弧の文字列はエスケープが必要ないため使いやすいです。: ```lua vim.cmd([[%s/\Vfoo/bar/g]]) ``` ### vim.api.nvim_replace_termcodes() このAPI関数はターミナルコードとVimのキーコードをエスケープできます。 次のようなマッピングを見たことがあるかもしれません。: ```vim inoremap pumvisible() ? "\" : "\" ``` 同じことをLuaでやると大変です。次のようにやるかもしれません。: ```lua function _G.smart_tab() return vim.fn.pumvisible() == 1 and [[\]] or [[\]] end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) ``` マッピングに `\` と `\` が挿入されているのを知るためだけに... キーコードをエスケープできるのは、Vim scriptの機能です。`\r`, `\42` や `\x10` のような多くのプログラミング言語に共通する通常のエスケープシーケンスとは別に、Vim scriptの `expr-quotes` (ダブルクォートで囲まれる文字列)を使用すると、人間が読める表現のVimキーコードをエスケープします。 Luaにはそのような機能は組み込まれていません。嬉しいことに、NeovimにはターミナルコードとキーコードをエスケープするAPI関数 `nvim_replace_termcodes()` があります。: ```lua print(vim.api.nvim_replace_termcodes('', true, true, true)) ``` これは少し冗長です。再利用できるラッパーを作ると便利です。: ```lua -- `termcodes` 専用の `t` 関数です -- この名前で呼ばなくてもいいですが、この簡潔さが便利です local function t(str) -- 必要に応じてboolean引数で調整します return vim.api.nvim_replace_termcodes(str, true, true, true) end print(t'') ``` 先程の例はこれで期待通りに動きます: ```lua local function t(str) return vim.api.nvim_replace_termcodes(str, true, true, true) end function _G.smart_tab() return vim.fn.pumvisible() == 1 and t'' or t'' end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) ``` `vim.keymap.set()`では、このハックは必要ありません。`expr`が有効な場合、デフォルトで自動的に変換されます。: ```lua vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and '' or '' end, {expr = true}) ``` 参照: - [`:help keycodes`](https://neovim.io/doc/user/intro.html#keycodes) - [`:help expr-quote`](https://neovim.io/doc/user/eval.html#expr-quote) - [`:help nvim_replace_termcodes()`](https://neovim.io/doc/user/api.html#nvim_replace_termcodes()) ## vimオプションを管理する ### API関数を使用する Neovimは、オプションの値を読み書きできるAPI関数を提供しています。 - グローバルオプション: - [`vim.api.nvim_set_option()`](https://neovim.io/doc/user/api.html#nvim_set_option()) - [`vim.api.nvim_get_option()`](https://neovim.io/doc/user/api.html#nvim_get_option()) - バッファオプション: - [`vim.api.nvim_buf_set_option()`](https://neovim.io/doc/user/api.html#nvim_buf_set_option()) - [`vim.api.nvim_buf_get_option()`](https://neovim.io/doc/user/api.html#nvim_buf_get_option()) - ウィンドウオプション: - [`vim.api.nvim_win_set_option()`](https://neovim.io/doc/user/api.html#nvim_win_set_option()) - [`vim.api.nvim_win_get_option()`](https://neovim.io/doc/user/api.html#nvim_win_get_option()) それらはオプションの名前と設定したい値を含む文字列を受け取ります。 boolな(`(no)number`のような)オプションは`true`か`false`のどちらかに設定する必要があります。: ```lua vim.api.nvim_set_option('smarttab', false) print(vim.api.nvim_get_option('smarttab')) -- false ``` 当然ながら、文字列のオプションには文字列を設定する必要があります。: ```lua vim.api.nvim_set_option('selection', 'exclusive') print(vim.api.nvim_get_option('selection')) -- 'exclusive' ``` 数値のオプションは数値を受け取ります。: ```lua vim.api.nvim_set_option('updatetime', 3000) print(vim.api.nvim_get_option('updatetime')) -- 3000 ``` バッファローカルとウィンドウローカルなオプションはそれぞれの番号も必要です。(`0`を指定した場合、カレントバッファ/ウィンドウが対象になります。): ```lua vim.api.nvim_win_set_option(0, 'number', true) vim.api.nvim_buf_set_option(10, 'shiftwidth', 4) print(vim.api.nvim_win_get_option(0, 'number')) -- true print(vim.api.nvim_buf_get_option(10, 'shiftwidth')) -- 4 ``` ### メタアクセサーを使用する もっと使い慣れた方法でオプションを設定したい場合、いくつかのメタアクセサーを使用できます。それらは、上記のAPI関数をラップしたものでオプションを変数のように操作できます。: - [`vim.o.{option}`](https://neovim.io/doc/user/lua.html#vim.o): `:let &{option-name}`のように動作します - [`vim.go.{option}`](https://neovim.io/doc/user/lua.html#vim.go): `:let &g:{option-name}`のように動作します - [`vim.bo.{option}`](https://neovim.io/doc/user/lua.html#vim.bo): バッファローカルオプションの場合`:let &l:{option-name}`のように動作します - [`vim.wo.{option}`](https://neovim.io/doc/user/lua.html#vim.wo): ウィンドウローカルオプションの場合`:let &l:{option-name}`のように動作します ```lua vim.o.smarttab = false -- let &smarttab = v:false print(vim.o.smarttab) -- false vim.o.isfname = vim.o.isfname .. ',@-@' -- on Linux: let &isfname = &isfname .. ',@-@' print(vim.o.isfname) -- '@,48-57,/,.,-,_,+,,,#,$,%,~,=,@-@' vim.bo.shiftwidth = 4 print(vim.bo.shiftwidth) -- 4 ``` バッファとウィンドウの番号を指定できます。0を指定した場合、カレントバッファ/ウィンドウが使用されます。: ```lua vim.bo[4].expandtab = true -- same as vim.api.nvim_buf_set_option(4, 'expandtab', true) vim.wo.number = true -- same as vim.api.nvim_win_set_option(0, 'number', true) ``` これらには、Luaで設定するのに便利なより洗練されたラッパーとして`vim.opt`があります。 `init.vim`で慣れているものと似ています。: - `vim.opt.{option}`: `:set`のように動作します - `vim.opt_global.{option}`: `:setglobal`のように動作します - `vim.opt_local.{option}`: `:setlocal`のように動作します ```lua vim.opt.smarttab = false print(vim.opt.smarttab:get()) -- false ``` いくつかのオプションはLuaのテーブルを使用して設定できます。: ```lua vim.opt.completeopt = {'menuone', 'noselect'} print(vim.inspect(vim.opt.completeopt:get())) -- { "menuone", "noselect" } ``` list、map、setのようなオプションのラッパーには、Vim scriptの`:set+=`, `:set^=`, `:set-=`と同じように動作するメソッドとメタメソッドが用意されています。 ```lua vim.opt.shortmess:append({ I = true }) -- どちらも等価です: vim.opt.shortmess = vim.opt.shortmess + { I = true } vim.opt.whichwrap:remove({ 'b', 's' }) -- どちらも等価です: vim.opt.whichwrap = vim.opt.whichwrap - { 'b', 's' } ``` 詳細は、必ず[`:help vim.opt`](https://neovim.io/doc/user/lua.html#vim.opt)を参照してください。 参照: - [`:help lua-vim-options`](https://neovim.io/doc/user/lua.html#lua-vim-options) ## vim内部の変数を管理する ### API関数を使用する オプションのように、内部変数にもAPI関数があります。 - グローバル変数 (`g:`): - [`vim.api.nvim_set_var()`](https://neovim.io/doc/user/api.html#nvim_set_var()) - [`vim.api.nvim_get_var()`](https://neovim.io/doc/user/api.html#nvim_get_var()) - [`vim.api.nvim_del_var()`](https://neovim.io/doc/user/api.html#nvim_del_var()) - バッファ変数 (`b:`): - [`vim.api.nvim_buf_set_var()`](https://neovim.io/doc/user/api.html#nvim_buf_set_var()) - [`vim.api.nvim_buf_get_var()`](https://neovim.io/doc/user/api.html#nvim_buf_get_var()) - [`vim.api.nvim_buf_del_var()`](https://neovim.io/doc/user/api.html#nvim_buf_del_var()) - ウィンドウ変数 (`w:`): - [`vim.api.nvim_win_set_var()`](https://neovim.io/doc/user/api.html#nvim_win_set_var()) - [`vim.api.nvim_win_get_var()`](https://neovim.io/doc/user/api.html#nvim_win_get_var()) - [`vim.api.nvim_win_del_var()`](https://neovim.io/doc/user/api.html#nvim_win_del_var()) - タブ変数 (`t:`): - [`vim.api.nvim_tabpage_set_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_set_var()) - [`vim.api.nvim_tabpage_get_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_get_var()) - [`vim.api.nvim_tabpage_del_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_del_var()) - Vimの定義済み変数 (`v:`): - [`vim.api.nvim_set_vvar()`](https://neovim.io/doc/user/api.html#nvim_set_vvar()) - [`vim.api.nvim_get_vvar()`](https://neovim.io/doc/user/api.html#nvim_get_vvar()) Vimの定義済み変数を除いて、削除できます(Vim scriptの`:unlet`と同様です)。 ローカル変数(`l:`)、スクリプト変数(`s:`)、関数の引数(`a:`)はVim script内でのみ意味があるため操作できません。 Luaには独自のスコープルールがあります。 これらの変数が不慣れな場合、[`:help internal-variables`](https://neovim.io/doc/user/eval.html#internal-variables)に説明があります。 これらの関数は対象の変数名と、設定したい値を含む文字列を受け取ります。 ```lua vim.api.nvim_set_var('some_global_variable', { key1 = 'value', key2 = 300 }) print(vim.inspect(vim.api.nvim_get_var('some_global_variable'))) -- { key1 = "value", key2 = 300 } vim.api.nvim_del_var('some_global_variable') ``` バッファ、ウィンドウ、タブページなスコープを持つ変数はそれぞれの番号を受け取ります(0を指定した場合は現在のバッファ/ウィンドウ/タブページが使われます。)。: ```lua vim.api.nvim_win_set_var(0, 'some_window_variable', 2500) vim.api.nvim_tab_set_var(3, 'some_tabpage_variable', 'hello world') print(vim.api.nvim_win_get_var(0, 'some_window_variable')) -- 2500 print(vim.api.nvim_buf_get_var(3, 'some_tabpage_variable')) -- 'hello world' vim.api.nvim_win_del_var(0, 'some_window_variable') vim.api.nvim_buf_del_var(3, 'some_tabpage_variable') ``` ### メタアクセサーを使用する 内部の変数はメタアクセサーを使用し、もっと直感的に操作できます。: - [`vim.g.{name}`](https://neovim.io/doc/user/lua.html#vim.g): グローバル変数 - [`vim.b.{name}`](https://neovim.io/doc/user/lua.html#vim.b): バッファ変数 - [`vim.w.{name}`](https://neovim.io/doc/user/lua.html#vim.w): ウィンドウ変数 - [`vim.t.{name}`](https://neovim.io/doc/user/lua.html#vim.t): タブ変数 - [`vim.v.{name}`](https://neovim.io/doc/user/lua.html#vim.v): Vimの定義済み変数 - [`vim.env.{name}`](https://neovim.io/doc/user/lua.html#vim.env): 環境変数 ```lua vim.g.some_global_variable = { key1 = 'value', key2 = 300 } print(vim.inspect(vim.g.some_global_variable)) -- { key1 = "value", key2 = 300 } -- 特定のバッファ/ウィンドウ/タブを対象とします(Neovim 0.6+) vim.b[2].myvar = 1 ``` 一部の変数名には、Luaの識別子に使用できない文字が含まれている場合があります。 この構文を使用してこれらの変数を操作できます。: `vim.g['my#variable']` 変数を削除するには単に`nil`を代入します。: ```lua vim.g.some_global_variable = nil ``` 参照: - [`:help lua-vim-variables`](https://neovim.io/doc/user/lua.html#lua-vim-variables) #### 警告 辞書の1つのキーを追加/更新/削除できません。例えば、次のVim scriptは期待通りに動きません。: ```vim let g:variable = {} lua vim.g.variable.key = 'a' echo g:variable " {} ``` 一時的な変数を使用する回避策があります: ```vim let g:variable = {} lua << EOF local tmp = vim.g.variable tmp.key = 'a' vim.g.variable = tmp EOF echo g:variable " {'key': 'a'} ``` 既知のissue: - [Issue #12544](https://github.com/neovim/neovim/issues/12544) ## Vim scriptの関数を呼び出す ### vim.fn.{function}() `vim.fn`は、Vim script組込みの関数を呼び出せます。 型はVimとLuaとで変換されます。 ```lua print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) print(vim.inspect(reversed_list)) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) end vim.fn.jobstart('ls', { on_stdout = print_stdout }) ``` ハッシュ(`#`)はLuaで有効な識別子ではないため、autoload関数は次の構文で呼び出す必要があります。: ```lua vim.fn['my#autoload#function']() ``` `vim.fn`は`vim.call`と同じ動作ですが、よりLuaらしい構文を使用できます。 `vim.api.nvim_call_function`とは、Vim/Luaオブジェクトを自動で変換する点が異なります。: `vim.api.nvim_call_function`は浮動小数点数のテーブルを返しLuaのクロージャーを受け入れませんが、`vim.fn`はこれらの型を扱えます。 参照: - [`:help vim.fn`](https://neovim.io/doc/user/lua.html#vim.fn) #### Tips Neovimにはプラグインに便利な強力な組込み関数を含むライブラリがあります。 アルファベット順のリストは[`:help vim-function`](https://neovim.io/doc/user/eval.html#vim-function)を参照してください。 [`:help function-list`](https://neovim.io/doc/user/usr_41.html#function-list)は機能別に分類されたリストです。 NeovimのAPI関数は`vim.api{..}`のように直接使用できます。 詳細は[`:help api`](https://neovim.io/doc/user/api.html#API)を参照してください。 #### 警告 いくつかのVim関数はbool値の変わりに`1`か`0`を返します。これは、Vim scriptでは`1`は真で`0`は偽になるため問題ありません。 次のようなことが可能です。: ```vim if has('nvim') " do something... endif ``` しかし、Luaで偽になるのは`false`と`nil`のみで、数値は値に関係なく常に`true`と評価されます。 明示的に`1`か`0`かをチェックする必要があります。: ```lua if vim.fn.has('nvim') == 1 then -- do something... end ``` ## マッピングを定義する ### API関数 Neovimはマッピングを設定、取得、削除するためのAPI関数を提供します。: - グローバルマッピング: - [`vim.api.nvim_set_keymap()`](https://neovim.io/doc/user/api.html#nvim_set_keymap()) - [`vim.api.nvim_get_keymap()`](https://neovim.io/doc/user/api.html#nvim_get_keymap()) - [`vim.api.nvim_del_keymap()`](https://neovim.io/doc/user/api.html#nvim_del_keymap()) - バッファローカルマッピング: - [`vim.api.nvim_buf_set_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_set_keymap()) - [`vim.api.nvim_buf_get_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_get_keymap()) - [`vim.api.nvim_buf_del_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_del_keymap()) `vim.api.nvim_set_keymap()`と`vim.api.nvim_buf_set_keymap()`から始めましょう。 最初の引数には有効にするモードの名前を含む文字列を渡します。: | String value | Help page | Affected modes | Vimscript equivalent | | ---------------------- | ------------- | ---------------------------------------- | -------------------- | | `''` (an empty string) | `mapmode-nvo` | Normal, Visual, Select, Operator-pending | `:map` | | `'n'` | `mapmode-n` | Normal | `:nmap` | | `'v'` | `mapmode-v` | Visual and Select | `:vmap` | | `'s'` | `mapmode-s` | Select | `:smap` | | `'x'` | `mapmode-x` | Visual | `:xmap` | | `'o'` | `mapmode-o` | Operator-pending | `:omap` | | `'!'` | `mapmode-ic` | Insert and Command-line | `:map!` | | `'i'` | `mapmode-i` | Insert | `:imap` | | `'l'` | `mapmode-l` | Insert, Command-line, Lang-Arg | `:lmap` | | `'c'` | `mapmode-c` | Command-line | `:cmap` | | `'t'` | `mapmode-t` | Terminal | `:tmap` | 2つ目の引数は、左側のマッピングを含む文字列(マッピングで定義されたコマンドを起動するためのキー)です。 空の文字列は``と同じで、キーを無効にします。 3つ目の引数は、右側のマッピングを含む文字列(実行するコマンド)です。 最後の引数は、[`:help :map-arguments`](https://neovim.io/doc/user/map.html#:map-arguments)で定義されているbool型のオプションのテーブルです(`noremap`を含み、`buffer`を除く)。 Neovim 0.7.0から、マッピング実行時、右側のマッピングの代わりに `callback` オプションに渡した関数を呼び出せます。 バッファローカルなマッピングは、バッファ番号を引数の最初に受け取ります(`0`を指定した場合、カレントバッファです)。 ```lua vim.api.nvim_set_keymap('n', '', ':set hlsearch!', { noremap = true, silent = true }) -- :nnoremap :set hlsearch vim.api.nvim_set_keymap('n', 'tegf', [[lua require('telescope.builtin').git_files()]], { noremap = true, silent = true }) -- :nnoremap tegf lua require('telescope.builtin').git_files() vim.api.nvim_buf_set_keymap(0, '', 'cc', 'line(".") == 1 ? "cc" : "ggcc"', { noremap = true, expr = true }) -- :noremap cc line('.') == 1 ? 'cc' : 'ggcc' vim.api.nvim_set_keymap('n', 'ex', '', { noremap = true, callback = function() print('My example') end, -- Lua関数は便利な文字列表現を持っていないため、 "desc" オプションを使用してマッピングの説明を記入できます。 desc = 'Prints "My example" in the message area', }) ``` `vim.api.nvim_get_keymap()`は、モードの省略名(上記の表を参照)を含む文字列を受け取ります。 そのモードにあるすべてのグローバルマッピングのテーブルを返します。 ```lua print(vim.inspect(vim.api.nvim_get_keymap('n'))) -- :verbose nmap ``` `vim.api.nvim_buf_get_keymap()`は、最初の引数に追加でバッファ番号を受け取ります(`0`を指定した場合、カレントバッファです)。 ```lua print(vim.inspect(vim.api.nvim_buf_get_keymap(0, 'i'))) -- :verbose imap ``` `vim.api.nvim_del_keymap()`は、モードと左側のマッピングを受け取ります。 ```lua vim.api.nvim_del_keymap('n', '') -- :nunmap ``` この場合でも、`vim.api.nvim_buf_del_keymap()`は最初の引数にバッファ番号を受け取ります。`0`を指定した場合、カレントバッファです。 ```lua vim.api.nvim_buf_del_keymap(0, 'i', '') -- :iunmap ``` ### vim.keymap :warning: このセクションで説明するAPI関数はNeovim 0.7.0+のみで使用できます。 Neovimはマッピングを設定/削除できる2つの関数を提供します: - [`vim.keymap.set()`](https://neovim.io/doc/user/lua.html#vim.keymap.set()) - [`vim.keymap.del()`](https://neovim.io/doc/user/lua.html#vim.keymap.del()) これらは、上記のAPI関数に糖類構文を追加したようなものです。 `vim.keymap.set()` は最初の引数として文字列を受け取ります。 また、複数のモードのマッピングを1度に定義するため、文字列のテーブルを受け取ることもできます: ```lua vim.keymap.set('n', 'ex1', 'lua vim.notify("Example 1")') vim.keymap.set({'n', 'c'}, 'ex2', 'lua vim.notify("Example 2")') ``` 2つ目の引数は左側のマッピングです。 3つ目の引数は右側のマッピングで、文字列かLua関数を受け取れます。 ```lua vim.keymap.set('n', 'ex1', 'echomsg "Example 1"') vim.keymap.set('n', 'ex2', function() print("Example 2") end) vim.keymap.set('n', 'pl1', require('plugin').plugin_action) -- モジュールの読み込みによる起動コストを避けるため、マッピングを呼び出したときにモジュールの遅延読みこみができるように関数でラップすることができます。: vim.keymap.set('n', 'pl2', function() require('plugin').plugin_action() end) ``` 4つ目の引数(省略可能)はオプションのテーブルで、 `vim.api.nvim_set_keymap()` に渡されるオプションに対応しており、いくつか追加項目があります([`:help vim.keymap.set()`](https://neovim.io/doc/user/lua.html#vim.keymap.set())に一覧があります)。 ```lua vim.keymap.set('n', 'ex1', 'echomsg "Example 1"', {buffer = true}) vim.keymap.set('n', 'ex2', function() print('Example 2') end, {desc = 'Prints "Example 2" to the message area'}) ``` 文字列を使用して定義するキーマップとLua関数で定義したキーマップは違います。 通常の`:nmap ex1`のようなキーマップ情報を表示する方法では、 `Lua function` とだけ表示され有用な情報（関数の内容自体）が表示されません。 キーマップの動作を説明する`desc`キーを追加するのを推奨します。 これはプラグインのマッピングのドキュメント化に特に重要です。 ユーザーはキーマップの使用方法をより簡単に理解できます。 このAPIが面白いところとして、Vimのマッピングの歴史的な癖をいくつか解消しています。 - `rhs` が `` マッピングである場合以外、デフォルトで `noremap` です。 このため、マッピングが再帰的であるかを考える必要はあまりないです。 ```lua vim.keymap.set('n', 'test1', 'echo "test"') -- :nnoremap test echo "test" -- マッピングを再帰的に行ないたい場合は、 `remap` オプションを `true` にします vim.keymap.set('n', '>', ']', {remap = true}) -- :nmap > ] -- マッピングは再帰的でないと機能しませんが、 vim.keymap.set() は自動的に処理します vim.keymap.set('n', 'plug', '(plugin)') -- :nmap plug (plugin) ``` - `expr` マッピングが有効なら、 Lua関数が返す文字列に対して `nvim_replace_termcodes()` が自動的に適用されます: ```lua vim.keymap.set('i', '', function() return vim.fn.pumvisible == 1 and '' or '' end, {expr = true}) ``` 参照: - [`:help recursive_mapping`](https://neovim.io/doc/user/map.html#recursive_mapping) `vim.keymap.del()` も同じように機能しますが、マッピングを削除します: ```lua vim.keymap.del('n', 'ex1') vim.keymap.del({'n', 'c'}, 'ex2', {buffer = true}) ``` ## ユーザーコマンドを定義する :warning: このセクションで説明するAPI関数はNeovim 0.7.0+のみで使用できます。 Neovimはユーザーコマンドを作成するAPI関数を提供します。 - Global user commands: - [`vim.api.nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command()) - [`vim.api.nvim_del_user_command()`](https://neovim.io/doc/user/api.html#nvim_del_user_command()) - Buffer-local user commands: - [`vim.api.nvim_buf_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_buf_create_user_command()) - [`vim.api.nvim_buf_del_user_command()`](https://neovim.io/doc/user/api.html#nvim_buf_del_user_command()) まず `vim.api.nvim_create_user_command()` から始めます 最初の引数はコマンドの名前です(名前は大文字で始める必要があります)。 2つめの引数はコマンドが呼びだされたときに実行するコードです。次のどちらかでコードを指定できます: 文字列(この場合、VimScriptとして実行されます)。`:commands` のように、``, `` などのエスケープシーケンスを使用できます。 ```lua vim.api.nvim_create_user_command('Upper', 'echo toupper()', { nargs = 1 }) -- :command! -nargs=1 Upper echo toupper() vim.cmd('Upper hello world') -- prints "HELLO WORLD" ``` もしくは、Lua関数。通常のエスケープシーケンスによって提供されるデータを含む、辞書のようなテーブルを受け取ります(利用できるキーのリストは[`:help nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command())で確認できます)。 ```lua vim.api.nvim_create_user_command( 'Upper', function(opts) print(string.upper(opts.args)) end, { nargs = 1 } ) ``` 3つめの引数はコマンドの属性をテーブルとして渡せます([`:help command-attributes`](https://neovim.io/doc/user/map.html#command-attributes)を参照)。`vim.api.nvim_buf_create_user_command()`を使用すればバッファローカルなユーザーコマンドを定義できるため、`-buffer`は有効な属性ではありません。 追加された2つの属性: - `desc`はLuaのコールバックとして定義されたコマンドに対して`:command {cmd}`を実行したときの表示内容を制御できます。 キーマップと同様、Lua関数として定義するコマンドには `desc`キーを追加するのを推奨します。 - `force`は`:command!`を呼び出すのと同じで、同じ名前のユーザーコマンドが既に存在する場合、そのコマンドを置き換えます。Vimscriptとは異なり、デフォルトでtrueです。 `-complete`属性は[`:help :command-complete`](https://neovim.io/doc/user/map.html#:command-complete)に記載されている属性に加え、Lua関数を取ることができます。 ```lua vim.api.nvim_create_user_command('Upper', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) -- return completion candidates as a list-like table return { 'foo', 'bar', 'baz' } end, }) ``` バッファローカルなユーザーコマンドも第1引数にバッファ番号を受け取ります。現在のバッファ用のコマンドを定義することができる`-buffer`より、これは便利です。 ```lua vim.api.nvim_buf_create_user_command(4, 'Upper', function() end, {}) ``` `vim.api.nvim_del_user_command()` はコマンド名を受け取ります。 ```lua vim.api.nvim_del_user_command('Upper') -- :delcommand Upper ``` ここでも、`vim.api.nvim_buf_del_user_command()`はバッファ番号を第1引数として受け取り、`0`は現在のバッファを表します。 ```lua vim.api.nvim_buf_del_user_command(4, 'Upper') ``` 参照: - [`:help nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command()) - [`:help 40.2`](https://neovim.io/doc/user/usr_40.html#40.2) - [`:help command-attributes`](https://neovim.io/doc/user/map.html#command-attributes) #### 警告 `-complete=custom`属性は自動的に補完候補をフィルタリングし、ワイルドカード([`:help wildcard`](https://neovim.io/doc/user/editing.html#wildcard))をサポートする機能を組み込みます: ```vim function! s:completion_function(ArgLead, CmdLine, CursorPos) abort return join([ \ 'strawberry', \ 'star', \ 'stellar', \ ], "\n") endfunction command! -nargs=1 -complete=custom,s:completion_function Test echo " `:Test st[ae]` と入力すると "star" と "stellar" を返します ``` `complete` にLua関数を渡すと、ユーザーにフィルタ方法を任せる`customlist`のような動作をします。 ```lua vim.api.nvim_create_user_command('Test', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) return { 'strawberry', 'star', 'stellar', } end, }) -- 候補リストをフィルタしてないので `:Test z` と入力すると全ての補完候補を返します ``` ## オートコマンドを定義する (この章は現在作成中です) Neovim 0.7.0はオートコマンド用のAPI関数を持っています。詳細は `:help api-autocmd` を参照してください。 - [Pull request #14661](https://github.com/neovim/neovim/pull/14661) (lua: autocmds take 2) ## ハイライトを定義する (この章は現在作成中です) Neovim 0.7.0はハイライトグループ用のAPI関数を持っています。 参照: - [`:help nvim_set_hl()`](https://neovim.io/doc/user/api.html#nvim_set_hl()) - [`:help nvim_get_hl_by_id()`](https://neovim.io/doc/user/api.html#nvim_get_hl_by_id()) - [`:help nvim_get_hl_by_name()`](https://neovim.io/doc/user/api.html#nvim_get_hl_by_name()) ## 一般的なTipsと推奨 ### キャッシュされたモジュールのリロード Luaでは、`require()`関数がモジュールをキャッシュします。 これはパフォーマンスには良いですが、後から`require()`を呼んでもモジュールは更新されないため少し面倒です。 特定のモジュールのキャッシュを更新する場合、`package.loaded`グローバルテーブルを変更する必要があります。: ```lua package.loaded['modname'] = nil require('modname') -- 新しい'modname'モジュールを読み込みます ``` [nvim-lua/plenary.nvim](https://github.com/nvim-lua/plenary.nvim)には、これを行う[関数](https://github.com/nvim-lua/plenary.nvim/blob/master/lua/plenary/reload.lua)があります。 ### Luaの文字列をパディングしないでください! 二重括弧の文字列を使用するとき、パディングの誘惑に負けないでください! スペースを無視するときは問題ないですが、スペースが重要な意味を持つときはデバックが困難な問題の原因になる可能性があります。: ```lua vim.api.nvim_set_keymap('n', 'f', [[ call foo() ]], {noremap = true}) ``` 上記の例では、`f`は`call foo()`ではなく`call foo()`にマッピングされます。 ### Vim script <--> Lua 型変換の注意 #### 変数を変換するとコピーが作られます: VimからLua、LuaからVimのオブジェクトの参照を直接操作できません。 例えば、Vim scriptの`map()`は変数をその場で変更します(破壊的)。 ```vim let s:list = [1, 2, 3] let s:newlist = map(s:list, {_, v -> v * 2}) echo s:list " [2, 4, 6] echo s:newlist " [2, 4, 6] echo s:list is# s:newlist " 1 ``` Luaからこの関数を使用すると、代りにコピーが作られます ```lua local tbl = {1, 2, 3} local newtbl = vim.fn.map(tbl, function(_, v) return v * 2 end) print(vim.inspect(tbl)) -- { 1, 2, 3 } print(vim.inspect(newtbl)) -- { 2, 4, 6 } print(tbl == newtbl) -- false ``` #### 変換を常にできるとは限りません これは主に関数とテーブルに影響します。 Luaのリストと辞書が混在するテーブルは変換できません。 ```lua print(vim.fn.count({1, 1, number = 1}, 1)) -- E5100: Cannot convert given lua table: table should either have a sequence of positive integer keys or contain only string keys ``` Luaで`vim.fn`を使用してVim関数を呼べますが、それらの参照を保持できません。 それは不測の動作の原因になります。: ```lua local FugitiveHead = vim.fn.funcref('FugitiveHead') print(FugitiveHead) -- vim.NIL vim.cmd("let g:test_dict = {'test_lambda': {-> 1}}") print(vim.g.test_dict.test_lambda) -- nil print(vim.inspect(vim.g.test_dict)) -- {} ``` Luaの関数をVimの関数に渡せますが、Vimの変数に格納できません。 (Neovim 0.7.0+で修正されて、格納できるようになりました。) ```lua -- This works: vim.fn.jobstart({'ls'}, { on_stdout = function(chan_id, data, name) print(vim.inspect(data)) end }) -- This doesn't: vim.g.test_dict = {test_lambda = function() return 1 end} -- Error: Cannot convert given lua type ``` ただし、Vim scriptから`luaeval()`を使用して同じことをすると**動作します**。: ```vim let g:test_dict = {'test_lambda': luaeval('function() return 1 end')} echo g:test_dict " {'test_lambda': function('4714')} ``` #### Vim booleans Vim scriptの一般的なパターンではbool値の代わりに`1`と`0`を使用します。 実際、Vimにはバージョン7.4.1154まで区別されたbool型がありませんでした。 Luaのbool値は数値ではなく、Vim scriptの実際のbool値に変換されます。: ```vim lua vim.g.lua_true = true echo g:lua_true " v:true lua vim.g.lua_false = false echo g:lua_false " v:false ``` ### リンターと言語サーバーの設定 Luaのプロジェクトでリンターや言語サーバーを使用して、診断と自動補完を利用している場合、Neovim固有の設定が必要になる場合があります。人気のあるツールの推奨設定は次のとおりです。: #### luacheck 次の設定を `~/.luacheckrc` (もしくは `$XDG_CONFIG_HOME/luacheck/.luacheckrc`)に配置すれば、[luacheck](https://github.com/mpeterv/luacheck/)でvimモジュールを認識できます。: ```lua globals = { "vim", } ``` 言語サーバーの[Alloyed/lua-lsp](https://github.com/Alloyed/lua-lsp/)は `luacheck` を使用してリンティングを提供し、同じファイルを読み込みます。 `luacheck` の設定方法の詳細は[ドキュメント](https://luacheck.readthedocs.io/en/stable/config.html)を参照してください。 #### sumneko/lua-language-server [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/)リポジトリに[sumneko/lua-language-serverの設定方法](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sumneko_lua)があります（例は組込みのLSPクライアントを使っていますが、他のLSPクライアントでも同じ設定である必要があります）。 [sumneko/lua-language-server](https://github.com/sumneko/lua-language-server/)の設定方法の詳細は["Setting"](https://github.com/sumneko/lua-language-server/wiki/Setting)を見てください。 #### coc.nvim [coc.nvim](https://github.com/neoclide/coc.nvim/)の補完ソースである[rafcamlet/coc-nvim-lua](https://github.com/rafcamlet/coc-nvim-lua/)はNeovim stdlibの項目を提供しています。 ### Luaコードのデバッグ 別のNeovimインスタンスで実行しているLuaコードを[jbyuki/one-small-step-for-vimkind](https://github.com/jbyuki/one-small-step-for-vimkind)でデバッグできます。 このプラグインは[Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)を使用しています。 デバッグアダプターに接続するには、[mfussenegger/nvim-dap](https://github.com/mfussenegger/nvim-dap/)や[puremourning/vimspector](https://github.com/puremourning/vimspector/)のようなDAPクライアントが必要です。 ### Luaマッピング/コマンド/オートコマンドのデバッグ マッピング/コマンド/オートコマンドが定義されている位置を `:verbose` コマンドで確認できます: ```vim :verbose map m ``` ```text n m_ * echo 'example' Last set from ~/.config/nvim/init.vim line 26 ``` デフォルトでは、Luaのパフォーマンス上の理由でこの機能は無効です。 Neovim起動時にverboseのレベルが0より上なら、この機能を有効にできます: ```sh nvim -V1 ``` 参照: - [`:help 'verbose'`](https://neovim.io/doc/user/options.html#'verbose') - [`:help -V`](https://neovim.io/doc/user/starting.html#-V) - [neovim/neovim#15079](https://github.com/neovim/neovim/pull/15079) ### Luaコードのテスト - [plenary.nvim: test harness](https://github.com/nvim-lua/plenary.nvim/#plenarytest_harness) - [notomo/vusted](https://github.com/notomo/vusted) ### Luarocksパッケージを使用する [wbthomason/packer.nvim](https://github.com/wbthomason/packer.nvim)はLuarocksパッケージをサポートしています。 使い方は[README](https://github.com/wbthomason/packer.nvim/#luarocks-support)にあります。 ## その他 ### vim.loop `vim.loop`はLibUV APIを公開するモジュールです。いくつかのリソース: - [Official documentation for LibUV](https://docs.libuv.org/en/v1.x/) - [Luv documentation](https://github.com/luvit/luv/blob/master/docs.md) - [teukka.tech - Using LibUV in Neovim](https://teukka.tech/posts/2020-01-07-vimloop/) 参照: - [`:help vim.loop`](https://neovim.io/doc/user/lua.html#vim.loop) ### vim.lsp `vim.lsp`は組込みのLSPクライアントを操作するためのモジュールです。 [neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/)は有名なLanguage Serverの設定集です。 クライアントの動作は"lsp-handlers"を使用して設定できます。詳細はこちら: - [`:help lsp-handler`](https://neovim.io/doc/user/lsp.html#lsp-handler) - [neovim/neovim#12655](https://github.com/neovim/neovim/pull/12655) - [How to migrate from diagnostic-nvim](https://github.com/nvim-lua/diagnostic-nvim/issues/73#issue-737897078) LSPクライアントを利用した[プラグイン](https://github.com/rockerBOO/awesome-neovim#lsp)も見たいかもしれません。 参照: - [`:help lsp`](https://neovim.io/doc/user/lsp.html#LSP) ### vim.treesitter `vim.treesitter`はNeovim内の[Tree-sitter](https://tree-sitter.github.io/tree-sitter/)ライブラリを操作するためのモジュールです。 Tree-sitterについてもっと知りたいなら、この[プレゼン (38:37)](https://www.youtube.com/watch?v=Jes3bD6P0To)に興味があるかもしれません。 [nvim-treesitter](https://github.com/nvim-treesitter/)オリジネーションは、ライブラリを利用して様々なプラグインをホストしています。 参照: - [`:help lua-treesitter`](https://neovim.io/doc/user/treesitter.html#lua-treesitter) ### トランスパイラ Luaを使用する利点の1つは実際にLuaを書く必要がないことです！利用できるトランスパイラはたくさんあります。 - [Moonscript](https://moonscript.org/) おそらく、最も知られているLuaのトランスパイラです。クラス、リスト内包表記、関数リテラルなどの便利な機能を多数追加します。 [svermeulen/nvim-moonmaker](https://github.com/svermeulen/nvim-moonmaker)はNeovimのプラグインと設定をMoonscriptで直接書けるようにします。 - [Fennel](https://fennel-lang.org/) lispをLuaにコンパイルします。[Olical/aniseed](https://github.com/Olical/aniseed)または、[Hotpot](https://github.com/rktjmp/hotpot.nvim)を使用するとNeovimのプラグインと設定を書くことができます。 さらに、[Olical/conjure](https://github.com/Olical/conjure)は対話的な開発環境を提供します(他の言語の中で)。 - [Teal](https://github.com/teal-language/tl) Tealの名前の由来はTL(typed lua)の発音からです。 まさにその通りで、強力な型をLuaに追加し、それ以外は標準のLuaの構文に近づけています。 [nvim-teal-maker](https://github.com/svermeulen/nvim-teal-maker)プラグインを使用して、 TealでNeovimプラグインや設定ファイルを書けます。 その他の興味深いプロジェクト: - [TypeScriptToLua/TypeScriptToLua](https://github.com/TypeScriptToLua/TypeScriptToLua) - [Haxe](https://haxe.org/) - [SwadicalRag/wasm2lua](https://github.com/SwadicalRag/wasm2lua) - [hengestone/lua-languages](https://github.com/hengestone/lua-languages) ================================================ FILE: README.md ================================================ :arrow_upper_left: (Feeling lost? Use the GitHub TOC!) **:warning: :warning: :warning: A more up-to-date version of this guide is available in the Neovim documentation, see [`:help lua-guide`](https://neovim.io/doc/user/lua-guide.html#lua-guide) :warning: :warning: :warning:** --- # Getting started using Lua in Neovim ## Translations - [Chinese version](https://github.com/glepnir/nvim-lua-guide-zh) - [Spanish version](https://github.com/RicardoRien/nvim-lua-guide/blob/master/README.esp.md) - [Portuguese version](https://github.com/npxbr/nvim-lua-guide/blob/master/README.pt-br.md) - [Japanese version](https://github.com/willelz/nvim-lua-guide-ja/blob/master/README.ja.md) - [Russian version](https://github.com/kuator/nvim-lua-guide-ru) - [Ukrainian version](https://github.com/famiclone/nvim-lua-guide-ua) - [Korean version](https://github.com/krapjost/nvim-lua-guide-kr) ## Introduction The [integration of Lua](https://www.youtube.com/watch?v=IP3J56sKtn0) as a [first-class language inside Neovim](https://github.com/neovim/neovim/wiki/FAQ#why-embed-lua-instead-of-x) is shaping up to be one of its killer features. However, the amount of teaching material for learning how to write plugins in Lua is not as large as what you would find for writing them in Vimscript. This is an attempt at providing some basic information to get people started. This guide assumes you are using at least version 0.5 of Neovim. ### Learning Lua If you are not already familiar with the language, there are plenty of resources to get started: - The [Learn X in Y minutes page about Lua](https://learnxinyminutes.com/docs/lua/) should give you a quick overview of the basics - [This guide](https://github.com/medwatt/Notes/blob/main/Lua/Lua_Quick_Guide.ipynb) is also a good resource for getting started quickly - If videos are more to your liking, Derek Banas has a [1-hour tutorial on the language](https://www.youtube.com/watch?v=iMacxZQMPXs) - Want something a little more interactive with runnable examples? Try [the LuaScript tutorial](https://www.luascript.dev/learn) - The [lua-users wiki](http://lua-users.org/wiki/LuaDirectory) is full of useful information on all kinds of Lua-related topics - The [official reference manual for Lua](https://www.lua.org/manual/5.1/) should give you the most comprehensive tour of the language (exists as a Vimdoc plugin if you want to read it from the comfort of your editor: [milisims/nvim-luaref](https://github.com/milisims/nvim-luaref)) It should also be noted that Lua is a very clean and simple language. It is easy to learn, especially if you have experience with similar scripting languages like JavaScript. You may already know more Lua than you realise! Note: the version of Lua that Neovim embeds is [LuaJIT](https://staff.fnwi.uva.nl/h.vandermeer/docs/lua/luajit/luajit_intro.html) 2.1.0, which maintains compatibility with Lua 5.1. ### Existing tutorials for writing Lua in Neovim A few tutorials have already been written to help people write plugins in Lua. Some of them helped quite a bit when writing this guide. Many thanks to their authors. - [teukka.tech - From init.vim to init.lua](https://teukka.tech/luanvim.html) - [dev.to - How to write neovim plugins in Lua](https://dev.to/2nit/how-to-write-neovim-plugins-in-lua-5cca) - [dev.to - How to make UI for neovim plugins in Lua](https://dev.to/2nit/how-to-make-ui-for-neovim-plugins-in-lua-3b6e) - [ms-jpq - Neovim Async Tutorial](https://github.com/ms-jpq/neovim-async-tutorial) - [oroques.dev - Neovim 0.5 features and the switch to init.lua](https://oroques.dev/notes/neovim-init/) - [Building A Vim Statusline from Scratch - jdhao's blog](https://jdhao.github.io/2019/11/03/vim_custom_statusline/) - [Configuring Neovim using Lua](https://icyphox.sh/blog/nvim-lua/) - [Devlog | Everything you need to know to configure neovim using lua](https://vonheikemen.github.io/devlog/tools/configuring-neovim-using-lua/) ### Companion plugins - [Vimpeccable](https://github.com/svermeulen/vimpeccable) - Plugin to help write your .vimrc in Lua - [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) - All the lua functions I don't want to write twice - [popup.nvim](https://github.com/nvim-lua/popup.nvim) - An implementation of the Popup API from vim in Neovim - [nvim_utils](https://github.com/norcalli/nvim_utils) - [nvim-luadev](https://github.com/bfredl/nvim-luadev) - REPL/debug console for nvim lua plugins - [nvim-luapad](https://github.com/rafcamlet/nvim-luapad) - Interactive real time neovim scratchpad for embedded lua engine - [nlua.nvim](https://github.com/tjdevries/nlua.nvim) - Lua Development for Neovim - [BetterLua.vim](https://github.com/euclidianAce/BetterLua.vim) - Better Lua syntax highlighting in Vim/NeoVim ## Where to put Lua files ### init.lua Neovim supports loading an `init.lua` file for configuration instead of the usual `init.vim`. Note: `init.lua` is of course _completely_ optional. Support for `init.vim` is not going away and is still a valid option for configuration. Do keep in mind that some features are not 100% exposed to Lua yet. See also: - [`:help config`](https://neovim.io/doc/user/starting.html#config) ### Modules Lua modules are found inside a `lua/` folder in your `'runtimepath'` (for most users, this will mean `~/.config/nvim/lua` on \*nix systems and `~/AppData/Local/nvim/lua` on Windows). You can `require()` files in this folder as Lua modules. Let's take the following folder structure as an example: ```text 📂 ~/.config/nvim ├── 📁 after ├── 📁 ftplugin ├── 📂 lua │ ├── 🌑 myluamodule.lua │ └── 📂 other_modules │ ├── 🌑 anothermodule.lua │ └── 🌑 init.lua ├── 📁 pack ├── 📁 plugin ├── 📁 syntax └── 🇻 init.vim ``` The following Lua code will load `myluamodule.lua`: ```lua require('myluamodule') ``` Notice the absence of a `.lua` extension. Similarly, loading `other_modules/anothermodule.lua` is done like so: ```lua require('other_modules.anothermodule') -- or require('other_modules/anothermodule') ``` Path separators are denoted by either a dot `.` or a slash `/`. A folder containing an `init.lua` file can be required directly, without having to specify the name of the file. ```lua require('other_modules') -- loads other_modules/init.lua ``` Requiring a nonexistent module or a module which contains syntax errors aborts the currently executing script. `pcall()` may be used to prevent errors. ```lua local ok, _ = pcall(require, 'module_with_error') if not ok then -- not loaded end ``` See also: - [`:help lua-require`](https://neovim.io/doc/user/lua.html#lua-require) #### Tips Several Lua plugins might have identical filenames in their `lua/` folder. This could lead to namespace clashes. If two different plugins have a `lua/main.lua` file, then doing `require('main')` is ambiguous: which file do we want to source? It might be a good idea to namespace your config or your plugin with a top-level folder, like so: `lua/plugin_name/main.lua` ### Runtime files Much like Vimscript files, Lua files can be loaded automatically from special folders in your `runtimepath`. Currently, the following folders are supported: - `colors/` - `compiler/` - `ftplugin/` - `ftdetect/` - `indent/` - `plugin/` - `syntax/` Note: in a runtime directory, all `*.vim` files are sourced before `*.lua` files. See also: - [`:help 'runtimepath'`](https://neovim.io/doc/user/options.html#'runtimepath') - [`:help load-plugins`](https://neovim.io/doc/user/starting.html#load-plugins) #### Tips Since runtime files aren't based on the Lua module system, two plugins can have a `plugin/main.lua` file without it being an issue. ## Using Lua from Vimscript ### :lua This command executes a chunk of Lua code. ```vim :lua require('myluamodule') ``` Multi-line scripts are possible using heredoc syntax: ```vim echo "Here's a bigger chunk of Lua code" lua << EOF local mod = require('mymodule') local tbl = {1, 2, 3} for k, v in ipairs(tbl) do mod.method(v) end print(tbl) EOF ``` Note: each `:lua` command has its own scope and variables declared with the `local` keyword are not accessible outside of the command. This won't work: ```vim :lua local foo = 1 :lua print(foo) " prints 'nil' instead of '1' ``` Note 2: the `print()` function in Lua behaves similarly to the `:echomsg` command. Its output is saved in the message-history and can be suppressed by the `:silent` command. See also: - [`:help :lua`](https://neovim.io/doc/user/lua.html#Lua) - [`:help :lua-heredoc`](https://neovim.io/doc/user/lua.html#:lua-heredoc) ### :luado This command executes a chunk of Lua code that acts on a range of lines in the current buffer. If no range is specified, the whole buffer is used instead. Whatever string is `return`ed from the chunk is used to determine what each line should be replaced with. The following command would replace every line in the current buffer with the text `hello world`: ```vim :luado return 'hello world' ``` Two implicit `line` and `linenr` variables are also provided. `line` is the text of the line being iterated upon whereas `linenr` is its number. The following command would make every line whose number is divisible by 2 uppercase: ```vim :luado if linenr % 2 == 0 then return line:upper() end ``` See also: - [`:help :luado`](https://neovim.io/doc/user/lua.html#:luado) ### Sourcing Lua files Neovim provides 3 Ex commands to source Lua files - `:luafile` - `:source` - `:runtime` `:luafile` and `:source` are very similar: ```vim :luafile ~/foo/bar/baz/myluafile.lua :luafile % :source ~/foo/bar/baz/myluafile.lua :source % ``` `:source` also supports ranges, which can be useful to only execute part of a script: ```vim :1,10source ``` `:runtime` is a little different: it uses the `'runtimepath'` option to determine which files to source. See [`:help :runtime`](https://neovim.io/doc/user/repeat.html#:runtime) for more details. See also: - [`:help :luafile`](https://neovim.io/doc/user/lua.html#:luafile) - [`:help :source`](https://neovim.io/doc/user/repeat.html#:source) - [`:help :runtime`](https://neovim.io/doc/user/repeat.html#:runtime) #### Sourcing a lua file vs calling require(): You might be wondering what the difference between calling the `require()` function and sourcing a Lua file is and whether you should prefer one way over the other. They have different use cases: - `require()`: - is a built-in Lua function. It allows you to take advantage of Lua's module system - searches for modules in `lua/` folders in your `'runtimepath'` - keeps track of what modules have been loaded and prevents a script from being parsed and executed a second time. If you change the file containing the code for a module and try to `require()` it a second time while Neovim is running, the module will not actually update - `:luafile`, `:source` and `:runtime`: - are Ex commands. They do not support modules - execute the contents of a script regardless of whether it has been executed before - `:luafile` and `:source` take a path that is either absolute or relative to the working directory of the current window - `:runtime` uses the `'runtimepath'` option to find files Files sourced via `:source`, `:runtime` or automatically from runtime directories will also show up in `:scriptnames` and `--startuptime` ### luaeval() This built-in Vimscript function evaluates a Lua expression string and returns its value. Lua data types are automatically converted to Vimscript types (and vice versa). ```vim " You can store the result in a variable let variable = luaeval('1 + 1') echo variable " 2 let concat = luaeval('"Lua".." is ".."awesome"') echo concat " 'Lua is awesome' " List-like tables are converted to Vim lists let list = luaeval('{1, 2, 3, 4}') echo list[0] " 1 echo list[1] " 2 " Note that unlike Lua tables, Vim lists are 0-indexed " Dict-like tables are converted to Vim dictionaries let dict = luaeval('{foo = "bar", baz = "qux"}') echo dict.foo " 'bar' " Same thing for booleans and nil echo luaeval('true') " v:true echo luaeval('nil') " v:null " You can create Vimscript aliases for Lua functions let LuaMathPow = luaeval('math.pow') echo LuaMathPow(2, 2) " 4 let LuaModuleFunction = luaeval('require("mymodule").myfunction') call LuaModuleFunction() " It is also possible to pass Lua functions as values to Vim functions lua X = function(k, v) return string.format("%s:%s", k, v) end echo map([1, 2, 3], luaeval("X")) ``` `luaeval()` takes an optional second argument that allows you to pass data to the expression. You can then access that data from Lua using the magic global `_A`: ```vim echo luaeval('_A[1] + _A[2]', [1, 1]) " 2 echo luaeval('string.format("Lua is %s", _A)', 'awesome') " 'Lua is awesome' ``` See also: - [`:help luaeval()`](https://neovim.io/doc/user/lua.html#luaeval()) ### v:lua This global Vim variable allows you to call Lua functions in the global namespace ([`_G`](https://www.lua.org/manual/5.1/manual.html#pdf-_G)) directly from Vimscript. Again, Vim data types are converted to Lua types and vice versa. ```vim call v:lua.print('Hello from Lua!') " 'Hello from Lua!' let scream = v:lua.string.rep('A', 10) echo scream " 'AAAAAAAAAA' " How about a nice statusline? lua << EOF function _G.statusline() local filepath = '%f' local align_section = '%=' local percentage_through_file = '%p%%' return string.format( '%s%s%s', filepath, align_section, percentage_through_file ) end EOF set statusline=%!v:lua.statusline() " Also works in expression mappings lua << EOF function _G.check_back_space() local col = vim.api.nvim_win_get_cursor(0)[2] return (col == 0 or vim.api.nvim_get_current_line():sub(col, col):match('%s')) and true end EOF inoremap \ pumvisible() ? "\" : \ v:lua.check_back_space() ? "\" : \ completion#trigger_completion() " Call a function from a Lua module by using single quotes and omitting parentheses: call v:lua.require'module'.foo() ``` See also: - [`:help v:lua`](https://neovim.io/doc/user/eval.html#v:lua) - [`:help v:lua-call`](https://neovim.io/doc/user/lua.html#v:lua-call) #### Caveats This variable can only be used to call functions. The following will always throw an error: ```vim " Aliasing functions doesn't work let LuaPrint = v:lua.print " Accessing dictionaries doesn't work echo v:lua.some_global_dict['key'] " Using a function as a value doesn't work echo map([1, 2, 3], v:lua.global_callback) ``` ### Tips You can get Lua syntax highlighting inside .vim files by putting `let g:vimsyn_embed = 'l'` in your configuration file. See [`:help g:vimsyn_embed`](https://neovim.io/doc/user/syntax.html#g:vimsyn_embed) for more on this option. ## The vim namespace Neovim exposes a global `vim` variable which serves as an entry point to interact with its APIs from Lua. It provides users with an extended "standard library" of functions as well as various sub-modules. Some notable functions and modules include: - `vim.inspect`: transform Lua objects into human-readable strings (useful for inspecting tables) - `vim.regex`: use Vim regexes from Lua - `vim.api`: module that exposes API functions (the same API used by remote plugins) - `vim.ui`: overridable UI functions that can be leveraged by plugins - `vim.loop`: module that exposes the functionality of Neovim's event-loop (using LibUV) - `vim.lsp`: module that controls the built-in LSP client - `vim.treesitter`: module that exposes the functionality of the tree-sitter library This list is by no means comprehensive. If you wish to know more about what's made available by the `vim` variable, [`:help lua-stdlib`](https://neovim.io/doc/user/lua.html#lua-stdlib) and [`:help lua-vim`](https://neovim.io/doc/user/lua.html#lua-vim) are the way to go. Alternatively, you can do `:lua print(vim.inspect(vim))` to get a list of every module. API functions are documented under [`:help api-global`](https://neovim.io/doc/user/api.html#api-global). #### Tips Writing `print(vim.inspect(x))` every time you want to inspect the contents of an object can get pretty tedious. It might be worthwhile to have a global wrapper function somewhere in your configuration (in Neovim 0.7.0+, this function is built-in, see [`:help vim.pretty_print()`](https://neovim.io/doc/user/lua.html#vim.pretty_print())): ```lua function _G.put(...) local objects = {} for i = 1, select('#', ...) do local v = select(i, ...) table.insert(objects, vim.inspect(v)) end print(table.concat(objects, '\n')) return ... end ``` You can then inspect the contents of an object very quickly in your code or from the command-line: ```lua put({1, 2, 3}) ``` ```vim :lua put(vim.loop) ``` Alternatively, you can use the `:lua` command to pretty-print a Lua expression by prefixing it with `=` (Neovim 0.7+ only): ```vim :lua =vim.loop ``` Additionally, you may find that built-in Lua functions are sometimes lacking compared to what you would find in other languages (for example `os.clock()` only returns a value in seconds, not milliseconds). Be sure to look at the Neovim stdlib (and `vim.fn`, more on that later), it probably has what you're looking for. ## Using Vimscript from Lua ### vim.api.nvim_eval() This function evaluates a Vimscript expression string and returns its value. Vimscript data types are automatically converted to Lua types (and vice versa). It is the Lua equivalent of the `luaeval()` function in Vimscript ```lua -- Data types are converted correctly print(vim.api.nvim_eval('1 + 1')) -- 2 print(vim.inspect(vim.api.nvim_eval('[1, 2, 3]'))) -- { 1, 2, 3 } print(vim.inspect(vim.api.nvim_eval('{"foo": "bar", "baz": "qux"}'))) -- { baz = "qux", foo = "bar" } print(vim.api.nvim_eval('v:true')) -- true print(vim.api.nvim_eval('v:null')) -- nil ``` #### Caveats Unlike `luaeval()`, `vim.api.nvim_eval()` does not provide an implicit `_A` variable to pass data to the expression. ### vim.api.nvim_exec() This function evaluates a chunk of Vimscript code. It takes in a string containing the source code to execute and a boolean to determine whether the output of the code should be returned by the function (you can then store the output in a variable, for example). ```lua local result = vim.api.nvim_exec( [[ let s:mytext = 'hello world' function! s:MyFunction(text) echo a:text endfunction call s:MyFunction(s:mytext) ]], true) print(result) -- 'hello world' ``` #### Caveats `nvim_exec` does not support script-local variables (`s:`) prior to Neovim 0.6.0 ### vim.api.nvim_command() This function executes an ex command. It takes in a string containing the command to execute. ```lua vim.api.nvim_command('new') vim.api.nvim_command('wincmd H') vim.api.nvim_command('set nonumber') vim.api.nvim_command('%s/foo/bar/g') ``` ### vim.cmd() Alias for `vim.api.nvim_exec()`. Only the command argument is needed, `output` is always set to `false`. ```lua vim.cmd('buffers') vim.cmd([[ let g:multiline_list = [ \ 1, \ 2, \ 3, \ ] echo g:multiline_list ]]) ``` #### Tips Since you have to pass strings to these functions, you often end up having to escape backslashes: ```lua vim.cmd('%s/\\Vfoo/bar/g') ``` Double bracketed strings are easier to use as they do not require escaping characters: ```lua vim.cmd([[%s/\Vfoo/bar/g]]) ``` ### vim.api.nvim_replace_termcodes() This API function allows you to escape terminal codes and Vim keycodes. You may have come across mappings like this one: ```vim inoremap pumvisible() ? "\" : "\" ``` Trying to do the same in Lua can prove to be a challenge. You might be tempted to do it like this: ```lua function _G.smart_tab() return vim.fn.pumvisible() == 1 and [[\]] or [[\]] end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) ``` only to find out that the mapping inserts `\` and `\` literally... Being able to escape keycodes is actually a Vimscript feature. Aside from the usual escape sequences like `\r`, `\42` or `\x10` that are common to many programming languages, Vimscript `expr-quotes` (strings surrounded with double quotes) allow you to escape the human-readable representation of Vim keycodes. Lua doesn't have such a feature built-in. Fortunately, Neovim has an API function for escaping terminal codes and keycodes: `nvim_replace_termcodes()` ```lua print(vim.api.nvim_replace_termcodes('', true, true, true)) ``` This is a little verbose. Making a reusable wrapper can help: ```lua -- The function is called `t` for `termcodes`. -- You don't have to call it that, but I find the terseness convenient local function t(str) -- Adjust boolean arguments as needed return vim.api.nvim_replace_termcodes(str, true, true, true) end print(t'') ``` Coming back to our earlier example, this should now work as expected: ```lua local function t(str) return vim.api.nvim_replace_termcodes(str, true, true, true) end function _G.smart_tab() return vim.fn.pumvisible() == 1 and t'' or t'' end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) ``` This is not necessary with `vim.keymap.set()` as it automatically transforms vim keycodes returned by Lua functions in `expr` mappings by default: ```lua vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and '' or '' end, {expr = true}) ``` See also: - [`:help keycodes`](https://neovim.io/doc/user/intro.html#keycodes) - [`:help expr-quote`](https://neovim.io/doc/user/eval.html#expr-quote) - [`:help nvim_replace_termcodes()`](https://neovim.io/doc/user/api.html#nvim_replace_termcodes()) ## Managing vim options ### Using api functions Neovim provides a set of API functions to either set an option or get its current value: - Global options: - [`vim.api.nvim_set_option()`](https://neovim.io/doc/user/api.html#nvim_set_option()) - [`vim.api.nvim_get_option()`](https://neovim.io/doc/user/api.html#nvim_get_option()) - Buffer-local options: - [`vim.api.nvim_buf_set_option()`](https://neovim.io/doc/user/api.html#nvim_buf_set_option()) - [`vim.api.nvim_buf_get_option()`](https://neovim.io/doc/user/api.html#nvim_buf_get_option()) - Window-local options: - [`vim.api.nvim_win_set_option()`](https://neovim.io/doc/user/api.html#nvim_win_set_option()) - [`vim.api.nvim_win_get_option()`](https://neovim.io/doc/user/api.html#nvim_win_get_option()) They take a string containing the name of the option to set/get as well as the value you want to set it to. Boolean options (like `(no)number`) have to be set to either `true` or `false`: ```lua vim.api.nvim_set_option('smarttab', false) print(vim.api.nvim_get_option('smarttab')) -- false ``` Unsurprisingly, string options have to be set to a string: ```lua vim.api.nvim_set_option('selection', 'exclusive') print(vim.api.nvim_get_option('selection')) -- 'exclusive' ``` Number options accept a number: ```lua vim.api.nvim_set_option('updatetime', 3000) print(vim.api.nvim_get_option('updatetime')) -- 3000 ``` Buffer-local and window-local options also need a buffer number or a window number (using `0` will set/get the option for the current buffer/window): ```lua vim.api.nvim_win_set_option(0, 'number', true) vim.api.nvim_buf_set_option(10, 'shiftwidth', 4) print(vim.api.nvim_win_get_option(0, 'number')) -- true print(vim.api.nvim_buf_get_option(10, 'shiftwidth')) -- 4 ``` ### Using meta-accessors A few meta-accessors are available if you want to set options in a more "idiomatic" way. They essentially wrap the above API functions and allow you to manipulate options as if they were variables: - [`vim.o`](https://neovim.io/doc/user/lua.html#vim.o): behaves like `:let &{option-name}` - [`vim.go`](https://neovim.io/doc/user/lua.html#vim.go): behaves like `:let &g:{option-name}` - [`vim.bo`](https://neovim.io/doc/user/lua.html#vim.bo): behaves like `:let &l:{option-name}` for buffer-local options - [`vim.wo`](https://neovim.io/doc/user/lua.html#vim.wo): behaves like `:let &l:{option-name}` for window-local options ```lua vim.o.smarttab = false -- let &smarttab = v:false print(vim.o.smarttab) -- false vim.o.isfname = vim.o.isfname .. ',@-@' -- on Linux: let &isfname = &isfname .. ',@-@' print(vim.o.isfname) -- '@,48-57,/,.,-,_,+,,,#,$,%,~,=,@-@' vim.bo.shiftwidth = 4 print(vim.bo.shiftwidth) -- 4 ``` You can specify a number for buffer-local and window-local options. If no number is given, the current buffer/window is used: ```lua vim.bo[4].expandtab = true -- same as vim.api.nvim_buf_set_option(4, 'expandtab', true) vim.wo.number = true -- same as vim.api.nvim_win_set_option(0, 'number', true) ``` These wrappers also have more sophisticated `vim.opt*` variants that provide convenient mechanisms for setting options in Lua. They're similar to what you might be used to in your `init.vim`: - `vim.opt`: behaves like `:set` - `vim.opt_global`: behaves like `:setglobal` - `vim.opt_local`: behaves like `:setlocal` ```lua vim.opt.smarttab = false print(vim.opt.smarttab:get()) -- false ``` Some options can be set using Lua tables: ```lua vim.opt.completeopt = {'menuone', 'noselect'} print(vim.inspect(vim.opt.completeopt:get())) -- { "menuone", "noselect" } ``` Wrappers for list-like, map-like and set-like options also come with methods and metamethods that work similarly to their `:set+=`, `:set^=` and `:set-=` counterparts in Vimscript. ```lua vim.opt.shortmess:append({ I = true }) -- alternative form: vim.opt.shortmess = vim.opt.shortmess + { I = true } vim.opt.whichwrap:remove({ 'b', 's' }) -- alternative form: vim.opt.whichwrap = vim.opt.whichwrap - { 'b', 's' } ``` Be sure to look at [`:help vim.opt`](https://neovim.io/doc/user/lua.html#vim.opt) for more information. See also: - [`:help lua-vim-options`](https://neovim.io/doc/user/lua.html#lua-vim-options) ## Managing vim internal variables ### Using api functions Much like options, internal variables have their own set of API functions: - Global variables (`g:`): - [`vim.api.nvim_set_var()`](https://neovim.io/doc/user/api.html#nvim_set_var()) - [`vim.api.nvim_get_var()`](https://neovim.io/doc/user/api.html#nvim_get_var()) - [`vim.api.nvim_del_var()`](https://neovim.io/doc/user/api.html#nvim_del_var()) - Buffer variables (`b:`): - [`vim.api.nvim_buf_set_var()`](https://neovim.io/doc/user/api.html#nvim_buf_set_var()) - [`vim.api.nvim_buf_get_var()`](https://neovim.io/doc/user/api.html#nvim_buf_get_var()) - [`vim.api.nvim_buf_del_var()`](https://neovim.io/doc/user/api.html#nvim_buf_del_var()) - Window variables (`w:`): - [`vim.api.nvim_win_set_var()`](https://neovim.io/doc/user/api.html#nvim_win_set_var()) - [`vim.api.nvim_win_get_var()`](https://neovim.io/doc/user/api.html#nvim_win_get_var()) - [`vim.api.nvim_win_del_var()`](https://neovim.io/doc/user/api.html#nvim_win_del_var()) - Tabpage variables (`t:`): - [`vim.api.nvim_tabpage_set_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_set_var()) - [`vim.api.nvim_tabpage_get_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_get_var()) - [`vim.api.nvim_tabpage_del_var()`](https://neovim.io/doc/user/api.html#nvim_tabpage_del_var()) - Predefined Vim variables (`v:`): - [`vim.api.nvim_set_vvar()`](https://neovim.io/doc/user/api.html#nvim_set_vvar()) - [`vim.api.nvim_get_vvar()`](https://neovim.io/doc/user/api.html#nvim_get_vvar()) With the exception of predefined Vim variables, they can also be deleted (the `:unlet` command is the equivalent in Vimscript). Local variables (`l:`), script variables (`s:`) and function arguments (`a:`) cannot be manipulated as they only make sense in the context of a Vim script, Lua has its own scoping rules. If you are unfamiliar with what these variables do, [`:help internal-variables`](https://neovim.io/doc/user/eval.html#internal-variables) describes them in detail. These functions take a string containing the name of the variable to set/get/delete as well as the value you want to set it to. ```lua vim.api.nvim_set_var('some_global_variable', { key1 = 'value', key2 = 300 }) print(vim.inspect(vim.api.nvim_get_var('some_global_variable'))) -- { key1 = "value", key2 = 300 } vim.api.nvim_del_var('some_global_variable') ``` Variables that are scoped to a buffer, a window or a tabpage also receive a number (using `0` will set/get/delete the variable for the current buffer/window/tabpage): ```lua vim.api.nvim_win_set_var(0, 'some_window_variable', 2500) vim.api.nvim_tab_set_var(3, 'some_tabpage_variable', 'hello world') print(vim.api.nvim_win_get_var(0, 'some_window_variable')) -- 2500 print(vim.api.nvim_buf_get_var(3, 'some_tabpage_variable')) -- 'hello world' vim.api.nvim_win_del_var(0, 'some_window_variable') vim.api.nvim_buf_del_var(3, 'some_tabpage_variable') ``` ### Using meta-accessors Internal variables can be manipulated more intuitively using these meta-accessors: - [`vim.g`](https://neovim.io/doc/user/lua.html#vim.g): global variables - [`vim.b`](https://neovim.io/doc/user/lua.html#vim.b): buffer variables - [`vim.w`](https://neovim.io/doc/user/lua.html#vim.w): window variables - [`vim.t`](https://neovim.io/doc/user/lua.html#vim.t): tabpage variables - [`vim.v`](https://neovim.io/doc/user/lua.html#vim.v): predefined Vim variables - [`vim.env`](https://neovim.io/doc/user/lua.html#vim.env): environment variables ```lua vim.g.some_global_variable = { key1 = 'value', key2 = 300 } print(vim.inspect(vim.g.some_global_variable)) -- { key1 = "value", key2 = 300 } -- target a specific buffer/window/tabpage (Neovim 0.6+) vim.b[2].myvar = 1 ``` Some variable names may contain characters that cannot be used for identifiers in Lua. You can still manipulate these variables by using this syntax: `vim.g['my#variable']`. To delete one of these variables, simply assign `nil` to it: ```lua vim.g.some_global_variable = nil ``` See also: - [`:help lua-vim-variables`](https://neovim.io/doc/user/lua.html#lua-vim-variables) #### Caveats You cannot add/update/delete keys from a dictionary stored in one of these variables. For example, this snippet of Vimscript code does not work as expected: ```vim let g:variable = {} lua vim.g.variable.key = 'a' echo g:variable " {} ``` You can use a temporary variable as a workaround: ```vim let g:variable = {} lua << EOF local tmp = vim.g.variable tmp.key = 'a' vim.g.variable = tmp EOF echo g:variable " {'key': 'a'} ``` This is a known issue: - [Issue #12544](https://github.com/neovim/neovim/issues/12544) ## Calling Vimscript functions ### vim.fn.{function}() `vim.fn` can be used to call a Vimscript function. Data types are converted back and forth from Lua to Vimscript. ```lua print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) print(vim.inspect(reversed_list)) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) end vim.fn.jobstart('ls', { on_stdout = print_stdout }) ``` Hashes (`#`) are not valid characters for identifiers in Lua, so autoload functions have to be called with this syntax: ```lua vim.fn['my#autoload#function']() ``` The functionality of `vim.fn` is identical to `vim.call`, but allows a more Lua-like syntax. It is distinct from `vim.api.nvim_call_function` in that converting Vim/Lua objects is automatic: `vim.api.nvim_call_function` returns a table for floating point numbers and does not accept Lua closures while `vim.fn` handles these types transparently. See also: - [`:help vim.fn`](https://neovim.io/doc/user/lua.html#vim.fn) #### Tips Neovim has an extensive library of powerful built-in functions that are very useful for plugins. See [`:help vim-function`](https://neovim.io/doc/user/eval.html#vim-function) for an alphabetical list and [`:help function-list`](https://neovim.io/doc/user/usr_41.html#function-list) for a list of functions grouped by topic. Neovim API functions can be used directly through `vim.api.{..}`. See [`:help api`](https://neovim.io/doc/user/api.html#API) for information. #### Caveats Some Vim functions that should return a boolean return `1` or `0` instead. This isn't a problem in Vimscript as `1` is truthy and `0` falsy, enabling constructs like these: ```vim if has('nvim') " do something... endif ``` In Lua however, only `false` and `nil` are considered falsy, numbers always evaluate to `true` no matter their value. You have to explicitly check for `1` or `0`: ```lua if vim.fn.has('nvim') == 1 then -- do something... end ``` ## Defining mappings ### API functions Neovim provides a list of API functions to set, get and delete mappings: - Global mappings: - [`vim.api.nvim_set_keymap()`](https://neovim.io/doc/user/api.html#nvim_set_keymap()) - [`vim.api.nvim_get_keymap()`](https://neovim.io/doc/user/api.html#nvim_get_keymap()) - [`vim.api.nvim_del_keymap()`](https://neovim.io/doc/user/api.html#nvim_del_keymap()) - Buffer-local mappings: - [`vim.api.nvim_buf_set_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_set_keymap()) - [`vim.api.nvim_buf_get_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_get_keymap()) - [`vim.api.nvim_buf_del_keymap()`](https://neovim.io/doc/user/api.html#nvim_buf_del_keymap()) Let's start with `vim.api.nvim_set_keymap()` and `vim.api.nvim_buf_set_keymap()` The first argument passed to the function is a string containing the name of the mode for which the mapping will take effect: | String value | Help page | Affected modes | Vimscript equivalent | | ---------------------- | ------------- | ---------------------------------------- | -------------------- | | `''` (an empty string) | `mapmode-nvo` | Normal, Visual, Select, Operator-pending | `:map` | | `'n'` | `mapmode-n` | Normal | `:nmap` | | `'v'` | `mapmode-v` | Visual and Select | `:vmap` | | `'s'` | `mapmode-s` | Select | `:smap` | | `'x'` | `mapmode-x` | Visual | `:xmap` | | `'o'` | `mapmode-o` | Operator-pending | `:omap` | | `'!'` | `mapmode-ic` | Insert and Command-line | `:map!` | | `'i'` | `mapmode-i` | Insert | `:imap` | | `'l'` | `mapmode-l` | Insert, Command-line, Lang-Arg | `:lmap` | | `'c'` | `mapmode-c` | Command-line | `:cmap` | | `'t'` | `mapmode-t` | Terminal | `:tmap` | The second argument is a string containing the left-hand side of the mapping (the key or set of keys that trigger the command defined in the mapping). An empty string is equivalent to ``, which disables a key. The third argument is a string containing the right-hand side of the mapping (the command to execute). The final argument is a table containing boolean options for the mapping as defined in [`:help :map-arguments`](https://neovim.io/doc/user/map.html#:map-arguments) (including `noremap` and excluding `buffer`). Since Neovim 0.7.0, you can also pass a `callback` option to invoke a Lua function instead of the right-hand side when executing the mapping. Buffer-local mappings also take a buffer number as their first argument (`0` sets the mapping for the current buffer). ```lua vim.api.nvim_set_keymap('n', '', ':set hlsearch!', { noremap = true, silent = true }) -- :nnoremap :set hlsearch vim.api.nvim_set_keymap('n', 'tegf', [[lua require('telescope.builtin').git_files()]], { noremap = true, silent = true }) -- :nnoremap tegf lua require('telescope.builtin').git_files() vim.api.nvim_buf_set_keymap(0, '', 'cc', 'line(".") == 1 ? "cc" : "ggcc"', { noremap = true, expr = true }) -- :noremap cc line('.') == 1 ? 'cc' : 'ggcc' vim.api.nvim_set_keymap('n', 'ex', '', { noremap = true, callback = function() print('My example') end, -- Since Lua function don't have a useful string representation, you can use the "desc" option to document your mapping desc = 'Prints "My example" in the message area', }) ``` `vim.api.nvim_get_keymap()` takes a string containing the shortname of the mode for which you want the list of mappings (see table above). The return value is a table containing all global mappings for the mode. ```lua print(vim.inspect(vim.api.nvim_get_keymap('n'))) -- :verbose nmap ``` `vim.api.nvim_buf_get_keymap()` takes an additional buffer number as its first argument (`0` will get mapppings for the current bufffer) ```lua print(vim.inspect(vim.api.nvim_buf_get_keymap(0, 'i'))) -- :verbose imap ``` `vim.api.nvim_del_keymap()` takes a mode and the left-hand side of a mapping. ```lua vim.api.nvim_del_keymap('n', '') -- :nunmap ``` Again, `vim.api.nvim_buf_del_keymap()`, takes a buffer number as its first argument, with `0` representing the current buffer. ```lua vim.api.nvim_buf_del_keymap(0, 'i', '') -- :iunmap ``` ### vim.keymap :warning: The functions discussed in this section are only available in Neovim 0.7.0+ Neovim provides two functions to set/del mappings: - [`vim.keymap.set()`](https://neovim.io/doc/user/lua.html#vim.keymap.set()) - [`vim.keymap.del()`](https://neovim.io/doc/user/lua.html#vim.keymap.del()) These are similar to the above API functions with added syntactic sugar. `vim.keymap.set()` takes a string as its first argument. It can also be a table of strings to define mappings for multiple modes at once: ```lua vim.keymap.set('n', 'ex1', 'lua vim.notify("Example 1")') vim.keymap.set({'n', 'c'}, 'ex2', 'lua vim.notify("Example 2")') ``` The second argument is the left-hand side of the mapping. The third argument is the right-hand side of the mapping, which can either be a string or a Lua function: ```lua vim.keymap.set('n', 'ex1', 'echomsg "Example 1"') vim.keymap.set('n', 'ex2', function() print("Example 2") end) vim.keymap.set('n', 'pl1', require('plugin').plugin_action) -- To avoid the startup cost of requiring the module, you can wrap it in a function to require it lazily when invoking the mapping: vim.keymap.set('n', 'pl2', function() require('plugin').plugin_action() end) ``` The fourth (optional) argument is a table of options that correspond to the options passed to `vim.api.nvim_set_keymap()`, with a few additions (see [`:help vim.keymap.set()`](https://neovim.io/doc/user/lua.html#vim.keymap.set()) for the full list). ```lua vim.keymap.set('n', 'ex1', 'echomsg "Example 1"', {buffer = true}) vim.keymap.set('n', 'ex2', function() print('Example 2') end, {desc = 'Prints "Example 2" to the message area'}) ``` Defining keymaps with a Lua function is different from using a string. The usual way to show information about a keymap like `:nmap ex1` will not output useful information (the string itself), but instead only show `Lua function`. It is recommended to add a `desc` key to describe the behavior of your keymap. This is especially important for documenting plugin mappings so users can understand the usage of the keymap more easily. An interesting feature of this API is that it irons out some historical quirks of Vim mappings: - Mappings are `noremap` by default, except when the `rhs` is a `` mapping. This means you rarely have to think about whether a mapping should be recursive or not: ```lua vim.keymap.set('n', 'test1', 'echo "test"') -- :nnoremap test echo "test" -- If you DO want the mapping to be recursive, set the "remap" option to "true" vim.keymap.set('n', '>', ']', {remap = true}) -- :nmap > ] -- mappings don't work unless they're recursive, vim.keymap.set() handles that for you automatically vim.keymap.set('n', 'plug', '(plugin)') -- :nmap plug (plugin) ``` - In `expr` mappings, `nvim_replace_termcodes()` is automatically applied to strings returned from Lua functions: ```lua vim.keymap.set('i', '', function() return vim.fn.pumvisible == 1 and '' or '' end, {expr = true}) ``` See also: - [`:help recursive_mapping`](https://neovim.io/doc/user/map.html#recursive_mapping) `vim.keymap.del()` works the same way but deletes mappings instead: ```lua vim.keymap.del('n', 'ex1') vim.keymap.del({'n', 'c'}, 'ex2', {buffer = true}) ``` ## Defining user commands :warning: The API functions discussed in this section are only available in Neovim 0.7.0+ Neovim provides API functions for user-defined commands: - Global user commands: - [`vim.api.nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command()) - [`vim.api.nvim_del_user_command()`](https://neovim.io/doc/user/api.html#nvim_del_user_command()) - Buffer-local user commands: - [`vim.api.nvim_buf_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_buf_create_user_command()) - [`vim.api.nvim_buf_del_user_command()`](https://neovim.io/doc/user/api.html#nvim_buf_del_user_command()) Let's start with `vim.api.nvim_create_user_command()` The first argument passed to this function is the name of the command (which must start with an uppercase letter). The second argument is the code to execute when invoking said command. It can either be: A string (in which case it will be executed as Vimscript). You can use escape sequences like ``, ``, etc. like you would with `:command` ```lua vim.api.nvim_create_user_command('Upper', 'echo toupper()', { nargs = 1 }) -- :command! -nargs=1 Upper echo toupper() vim.cmd('Upper hello world') -- prints "HELLO WORLD" ``` Or a Lua function. It receives a dictionary-like table that contains the data normally provided by escape sequences (see [`:help nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command()) for a list of available keys) ```lua vim.api.nvim_create_user_command( 'Upper', function(opts) print(string.upper(opts.args)) end, { nargs = 1 } ) ``` The third argument lets you pass command attributes as a table (see [`:help command-attributes`](https://neovim.io/doc/user/map.html#command-attributes)). Since you can already define buffer-local user commands with `vim.api.nvim_buf_create_user_command()`, `-buffer` is not a valid attribute. Two additional attributes are available: - `desc` allows you to control what gets displayed when you run `:command {cmd}` on a command defined as a Lua callback. Similarly to keymaps, it is recommended to add a `desc` key to commands defined as Lua functions. - `force` is equivalent to calling `:command!` and replaces a command if one with the same name already exists. It is true by default, unlike its Vimscript equivalent. The `-complete` attribute can take a Lua function in addition to the attributes listed in [`:help :command-complete`](https://neovim.io/doc/user/map.html#:command-complete). ```lua vim.api.nvim_create_user_command('Upper', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) -- return completion candidates as a list-like table return { 'foo', 'bar', 'baz' } end, }) ``` Buffer-local user commands also take a buffer number as their first argument. This is an advantage over `-buffer` which can only define a command for the current buffer. ```lua vim.api.nvim_buf_create_user_command(4, 'Upper', function() end, {}) ``` `vim.api.nvim_del_user_command()` takes a command name. ```lua vim.api.nvim_del_user_command('Upper') -- :delcommand Upper ``` Again, `vim.api.nvim_buf_del_user_command()`, takes a buffer number as its first argument, with `0` representing the current buffer. ```lua vim.api.nvim_buf_del_user_command(4, 'Upper') ``` See also: - [`:help nvim_create_user_command()`](https://neovim.io/doc/user/api.html#nvim_create_user_command()) - [`:help 40.2`](https://neovim.io/doc/user/usr_40.html#40.2) - [`:help command-attributes`](https://neovim.io/doc/user/map.html#command-attributes) ### Caveats The `-complete=custom` attribute automatically filters completion candidates and has built-in wildcard ([`:help wildcard`](https://neovim.io/doc/user/editing.html#wildcard)) support: ```vim function! s:completion_function(ArgLead, CmdLine, CursorPos) abort return join([ \ 'strawberry', \ 'star', \ 'stellar', \ ], "\n") endfunction command! -nargs=1 -complete=custom,s:completion_function Test echo " Typing `:Test st[ae]` returns "star" and "stellar" ``` Passing a Lua function to `complete` makes it behave like `customlist` which leaves filtering up to the user: ```lua vim.api.nvim_create_user_command('Test', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) return { 'strawberry', 'star', 'stellar', } end, }) -- Typing `:Test z` returns all the completion results because the list was not filtered ``` ## Defining autocommands (this section is a work in progress) Neovim 0.7.0 has API functions for autocommands. See `:help api-autocmd` for details - [Pull request #14661](https://github.com/neovim/neovim/pull/14661) (lua: autocmds take 2) ## Defining highlights (this section is a work in progress) Neovim 0.7.0 has API functions for highlight groups. See also: - [`:help nvim_set_hl()`](https://neovim.io/doc/user/api.html#nvim_set_hl()) - [`:help nvim_get_hl_by_id()`](https://neovim.io/doc/user/api.html#nvim_get_hl_by_id()) - [`:help nvim_get_hl_by_name()`](https://neovim.io/doc/user/api.html#nvim_get_hl_by_name()) ## General tips and recommendations ### Reloading cached modules In Lua, the `require()` function caches modules. This is a good thing for performance, but it can make working on plugins a bit cumbersome because modules are not updated on subsequent `require()` calls. If you'd like to refresh the cache for a particular module, you have to modify the `package.loaded` global table: ```lua package.loaded['modname'] = nil require('modname') -- loads an updated version of module 'modname' ``` The [nvim-lua/plenary.nvim](https://github.com/nvim-lua/plenary.nvim) plugin has a [custom function](https://github.com/nvim-lua/plenary.nvim/blob/master/lua/plenary/reload.lua) that does this for you. ### Don't pad Lua strings! When using double bracketed strings, resist the temptation to pad them! While it is fine to do in contexts where spaces are ignored, it can cause hard to debug issues when whitespace is significant: ```lua vim.api.nvim_set_keymap('n', 'f', [[ call foo() ]], {noremap = true}) ``` In the above example, `f` is mapped to `call foo()` instead of `call foo()`. ### Notes about Vimscript <-> Lua type conversion #### Converting a variable creates a copy: You can't directly interact with the reference to a Vim object from Lua or a Lua object from Vimscript. For example, the `map()` function in Vimscript modifies a variable in place: ```vim let s:list = [1, 2, 3] let s:newlist = map(s:list, {_, v -> v * 2}) echo s:list " [2, 4, 6] echo s:newlist " [2, 4, 6] echo s:list is# s:newlist " 1 ``` Using this function from Lua creates a copy instead: ```lua local tbl = {1, 2, 3} local newtbl = vim.fn.map(tbl, function(_, v) return v * 2 end) print(vim.inspect(tbl)) -- { 1, 2, 3 } print(vim.inspect(newtbl)) -- { 2, 4, 6 } print(tbl == newtbl) -- false ``` #### Conversion is not always possible This mostly affects functions and tables: Lua tables that are a mix between a List and a Dictionary can't be converted: ```lua print(vim.fn.count({1, 1, number = 1}, 1)) -- E5100: Cannot convert given lua table: table should either have a sequence of positive integer keys or contain only string keys ``` While you can call Vim functions in Lua with `vim.fn`, you can't hold references to them. This can cause surprising behaviors: ```lua local FugitiveHead = vim.fn.funcref('FugitiveHead') print(FugitiveHead) -- vim.NIL vim.cmd("let g:test_dict = {'test_lambda': {-> 1}}") print(vim.g.test_dict.test_lambda) -- nil print(vim.inspect(vim.g.test_dict)) -- {} ``` Passing Lua functions to Vim functions is OK, storing them in Vim variables is not (fixed in Neovim 0.7.0+): ```lua -- This works: vim.fn.jobstart({'ls'}, { on_stdout = function(chan_id, data, name) print(vim.inspect(data)) end }) -- This doesn't: vim.g.test_dict = {test_lambda = function() return 1 end} -- Error: Cannot convert given lua type ``` Note however that doing the same from Vimscript with `luaeval()` **does** work: ```vim let g:test_dict = {'test_lambda': luaeval('function() return 1 end')} echo g:test_dict " {'test_lambda': function('4714')} ``` #### Vim booleans A common pattern in Vim scripts is to use `1` or `0` instead of proper booleans. Indeed, Vim did not have a separate boolean type until version 7.4.1154. Lua booleans are converted to actual booleans in Vimscript, not numbers: ```vim lua vim.g.lua_true = true echo g:lua_true " v:true lua vim.g.lua_false = false echo g:lua_false " v:false ``` ### Setting up linters/language servers If you're using linters and/or language servers to get diagnostics and autocompletion for Lua projects, you may have to configure Neovim-specific settings for them. Here are a few recommended settings for popular tools: #### luacheck You can get [luacheck](https://github.com/mpeterv/luacheck/) to recognize the `vim` global by putting this configuration in `~/.luacheckrc` (or `$XDG_CONFIG_HOME/luacheck/.luacheckrc`): ```lua globals = { "vim", } ``` The [Alloyed/lua-lsp](https://github.com/Alloyed/lua-lsp/) language server uses `luacheck` to provide linting and reads the same file. For more information on how to configure `luacheck`, please refer to its [documentation](https://luacheck.readthedocs.io/en/stable/config.html) #### sumneko/lua-language-server The [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/) repository contains [instructions to configure sumneko/lua-language-server](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sumneko_lua) (the example uses the built-in LSP client but the configuration should be identical for other LSP client implementations). For more information on how to configure [sumneko/lua-language-server](https://github.com/sumneko/lua-language-server/) see ["Setting"](https://github.com/sumneko/lua-language-server/wiki/Setting) #### coc.nvim The [rafcamlet/coc-nvim-lua](https://github.com/rafcamlet/coc-nvim-lua/) completion source for [coc.nvim](https://github.com/neoclide/coc.nvim/) provides completion items for the Neovim stdlib. ### Debugging Lua code You can debug Lua code running in a separate Neovim instance with [jbyuki/one-small-step-for-vimkind](https://github.com/jbyuki/one-small-step-for-vimkind) The plugin uses the [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/). Connecting to a debug adapter requires a DAP client like [mfussenegger/nvim-dap](https://github.com/mfussenegger/nvim-dap/) or [puremourning/vimspector](https://github.com/puremourning/vimspector/). ### Debugging Lua mappings/commands/autocommands The `:verbose` command allows you to see where a mapping/command/autocommand was defined: ```vim :verbose map m ``` ```text n m_ * echo 'example' Last set from ~/.config/nvim/init.vim line 26 ``` By default, this feature is disabled in Lua for performance reasons. You can enable it by starting Neovim with a verbose level greater than 0: ```sh nvim -V1 ``` See also: - [`:help 'verbose'`](https://neovim.io/doc/user/options.html#'verbose') - [`:help -V`](https://neovim.io/doc/user/starting.html#-V) - [neovim/neovim#15079](https://github.com/neovim/neovim/pull/15079) ### Testing Lua code - [plenary.nvim: test harness](https://github.com/nvim-lua/plenary.nvim/#plenarytest_harness) - [notomo/vusted](https://github.com/notomo/vusted) ### Using Luarocks packages [wbthomason/packer.nvim](https://github.com/wbthomason/packer.nvim) supports Luarocks packages. Instructions for how to set this up are available in the [README](https://github.com/wbthomason/packer.nvim/#luarocks-support) ## Miscellaneous ### vim.loop `vim.loop` is the module that exposes the LibUV API. Some resources: - [Official documentation for LibUV](https://docs.libuv.org/en/v1.x/) - [Luv documentation](https://github.com/luvit/luv/blob/master/docs.md) - [teukka.tech - Using LibUV in Neovim](https://teukka.tech/posts/2020-01-07-vimloop/) See also: - [`:help vim.loop`](https://neovim.io/doc/user/lua.html#vim.loop) ### vim.lsp `vim.lsp` is the module that controls the built-in LSP client. The [neovim/nvim-lspconfig](https://github.com/neovim/nvim-lspconfig/) repository contains default configurations for popular language servers. The behavior of the client can be configured using "lsp-handlers". For more information: - [`:help lsp-handler`](https://neovim.io/doc/user/lsp.html#lsp-handler) - [neovim/neovim#12655](https://github.com/neovim/neovim/pull/12655) - [How to migrate from diagnostic-nvim](https://github.com/nvim-lua/diagnostic-nvim/issues/73#issue-737897078) You may also want to take a look at [plugins built around the LSP client](https://github.com/rockerBOO/awesome-neovim#lsp) See also: - [`:help lsp`](https://neovim.io/doc/user/lsp.html#LSP) ### vim.treesitter `vim.treesitter` is the module that controls the integration of the [Tree-sitter](https://tree-sitter.github.io/tree-sitter/) library in Neovim. If you want to know more about Tree-sitter, you may be interested in this [presentation (38:37)](https://www.youtube.com/watch?v=Jes3bD6P0To). The [nvim-treesitter](https://github.com/nvim-treesitter/) organisation hosts various plugins taking advantage of the library. See also: - [`:help lua-treesitter`](https://neovim.io/doc/user/treesitter.html#lua-treesitter) ### Transpilers One advantage of using Lua is that you don't actually have to write Lua code! There is a multitude of transpilers available for the language. - [Moonscript](https://moonscript.org/) Probably one of the most well-known transpilers for Lua. Adds a lots of convenient features like classes, list comprehensions or function literals. The [svermeulen/nvim-moonmaker](https://github.com/svermeulen/nvim-moonmaker) plugin allows you to write Neovim plugins and configuration directly in Moonscript. - [Fennel](https://fennel-lang.org/) A lisp that compiles to Lua. You can write configuration and plugins for Neovim in Fennel with the [Olical/aniseed](https://github.com/Olical/aniseed) or the [Hotpot](https://github.com/rktjmp/hotpot.nvim) plugin. Additionally, the [Olical/conjure](https://github.com/Olical/conjure) plugin provides an interactive development environment that supports Fennel (among other languages). - [Teal](https://github.com/teal-language/tl) The name Teal comes from pronouncing TL (typed lua). This is exactly what it tries to do - add strong typing to lua while otherwise remaining close to standard lua syntax. The [nvim-teal-maker](https://github.com/svermeulen/nvim-teal-maker) plugin can be used to write Neovim plugins or configuration files directly in Teal Other interesting projects: - [TypeScriptToLua/TypeScriptToLua](https://github.com/TypeScriptToLua/TypeScriptToLua) - [Haxe](https://haxe.org/) - [SwadicalRag/wasm2lua](https://github.com/SwadicalRag/wasm2lua) - [hengestone/lua-languages](https://github.com/hengestone/lua-languages) ================================================ FILE: doc/nvim-lua-guide.jax ================================================ *nvim-lua-guide.txt* Getting started using Lua in Neovim ============================================================================== はじめに *luaguide-introduction* Neovimのファーストクラス言語としてのLuaはキラー機能の1つになりつつあります。 しかし、Luaでプラグインを書くための教材はVim script程多くありません。これは、Luaを始めるための基本的な情報を提供する試みです。 このガイドは少なくともNeovim 0.5を使用していることを前提としています。 Luaを学ぶ~ まだLuaについて詳しくない場合、学ぶためのリソースはたくさんあります。: - Learn X in Y minutes page about Lua: https://learnxinyminutes.com/docs/lua/ は基本的な概要を説明します。 - このガイド https://github.com/medwatt/Notes/blob/main/Lua/Lua_Quick_Guide.ipynb も素早く始めるのに良いチュートリアルです。 - 動画が好きなら、Derek Banasの動画があります。 1-hour tutorial on the language: https://www.youtube.com/watch?v=iMacxZQMPXs - 実行できるサンプルを使い、対話的に学びたいですか？ LuaScript tutorial: https://www.luascript.dev/learn を試してみてください。 - lua-users wiki: http://lua-users.org/wiki/LuaDirectory にはLua関連のトピックごとの便利な情報がたくさんあります。 - official reference manual for Lua: https://www.lua.org/manual/5.1/ には最も包括的な情報があります。 エディタで快適に読みたいなら、Vimdocプラグインがあります。: milisims/nvim-luaref: https://github.com/milisims/nvim-luaref Luaはとてもクリーンでシンプルな言語であることに注意してください。 JavaScriptのようなスクリプト言語の経験があれば、学ぶことは簡単です。 あなたはもう自分で思っているよりLuaについて知っているかもしれません！ Note: Neovimに埋め込まれているLuaはLuaJIT: https://staff.fnwi.uva.nl/h.vandermeer/docs/lua/luajit/luajit_intro.html 2.1.0でLua 5.1と互換性を維持しています。 Luaを書くための既存のチュートリアル~ Luaでプラグインを書くためのチュートリアルが既にいくつかあります。 それらはこのガイドを書くのに役に立ちました。筆者に感謝します。 - teukka.tech - init.vimからinit.luaへ: https://teukka.tech/luanvim.html - 2n.pl - プラグインをLuaで書く方法: https://dev.to/2nit/how-to-write-neovim-plugins-in-lua-5cca - 2n.pl - プラグインのUIをLuaで作る方法: https://dev.to/2nit/how-to-make-ui-for-neovim-plugins-in-lua-3b6e - ms-jpq - Neovim Async Tutorial: https://github.com/ms-jpq/neovim-async-tutorial - oroques.dev - Neovim 0.5の機能とinit.luaへの切り替え: https://oroques.dev/notes/neovim-init/ - ゼロからステータスラインを作る - jdhao's blog: https://jdhao.github.io/2019/11/03/vim_custom_statusline/ - LuaでNeovimを設定する: https://icyphox.sh/blog/nvim-lua/ - Devlog | Luaで設定するために知る必要のあること: https://vonheikemen.github.io/devlog/tools/configuring-neovim-using-lua/ 関連するプラグイン~ - Vimpeccable: https://github.com/svermeulen/vimpeccable - .vimrc内でLuaを書くのに役に立つプラグイン - plenary.nvim: https://github.com/nvim-lua/plenary.nvim - 二度書きたくないLua関数のすべて - popup.nvim: https://github.com/nvim-lua/popup.nvim - vimのPopup APIのNeovimでの実装 - nvim_utils: https://github.com/norcalli/nvim_utils - nvim-luadev: https://github.com/bfredl/nvim-luadev - REPL/debugコンソール - nvim-luapad: https://github.com/rafcamlet/nvim-luapad - 組込みLuaエンジンのインタラクティブなリアルタイムスクラッチパッド - nlua.nvim: https://github.com/tjdevries/nlua.nvim - NeovimのLua開発 - BetterLua.vim: https://github.com/euclidianAce/BetterLua.vim - Vim/Neovimより良いシンタックスハイライト ============================================================================== Luaファイルを置く場所 *luaguide-where-to-put-lua-files* init.lua~ Neovimは、`init.vim`の代わりに設定ファイルとして`init.lua`を読み込むことをサポートしています。 Note: `init.lua`は_完全に_オプションです。`init.vim`は廃止されず、設定として有効です。 いくつかの機能は、まだ100%Luaに公開されていないので注意してください。 参照: - |config| モジュール~ Luaモジュールは、`'runtimepath'`内の`lua/`フォルダにあります(ほとんどの場合、 \*nixでは`~/.config/nvim/lua`、Windowsでは`~/AppData/Local/nvim/lua`を意味します)。 このフォルダにあるファイルをLuaモジュールとして`require()`できます。 例として次のフォルダ構造を取り上げましょう。: > 📂 ~/.config/nvim ├── 📁 after ├── 📁 ftplugin ├── 📂 lua │ ├── 🌑 myluamodule.lua │ └── 📂 other_modules │ ├── 🌑 anothermodule.lua │ └── 🌑 init.lua ├── 📁 pack ├── 📁 plugin ├── 📁 syntax └── 🇻 init.vim < 次のLuaコードは`myluamodule.lua`をロードします。: > require('myluamodule') < `.lua`拡張子がないことに注意してください。 同様に、`other_modules/anothermodule.lua` のロードは次のように行います。: > require('other_modules.anothermodule') -- or require('other_modules/anothermodule') < パスの区切りはドット`.`またはスラッシュ`/`で示されます。 フォルダに`init.lua`が含まれている場合、ファイル名を指定せずにロードできます。 > require('other_modules') -- other_modules/init.luaをロード < 存在しないモジュール、構文エラーを含むモジュールをrequireすると実行中のスクリプトは停止します。 エラーを防ぐために、`pcall()`を使用できます。 > local ok, _ = pcall(require, 'module_with_error') if not ok then -- not loaded end < 参照: - `:help lua-require` Runtime files~ Vim scriptと同様に、`runtimepath`内にある特定のフォルダからLuaファイルを自動的に読み込めます。 現在、次のフォルダがサポートされています。: - `colors/` - `compiler/` - `ftplugin/` - `ftdetect/` - `indent/` - `plugin/` - `syntax/` 参照: - `:help 'runtimepath'` Tips~ いくつかのLuaプラグインは`lua/`フォルダ内に同じ名前のファイルがあるかもしれません。 これにより、名前空間の衝突を起こす可能性があります。 異なる2つのプラグインに`lua/main.lua`がある場合、`require('main')`は曖昧です。: どのファイルを読み込みますか？ トップレベルのフォルダで名前空間をつけることをお勧めします。: `lua/plugin_name/main.lua` Runtime files~ Vim scriptと同様に、`runtimepath`内にある特定のフォルダからLuaファイルを自動的に読み込めます。 現在、次のフォルダがサポートされています。: - `colors/` - `compiler/` - `ftplugin/` - `ftdetect/` - `indent/` - `plugin/` - `syntax/` Note: runtimeデイレクトリでは、すべての`*.vim`ファイルは`*.lua`ファイルの前に読み込まれます。 参照: - `:help 'runtimepath'` - `:help load-plugins` Tips~ ランタイムファイルはLuaのモジュールシステムをベースとしていないため、2つのプラグインは`plugin/main.lua`を問題なく持つことができます。 ============================================================================== Vim scriptからLuaを使用する *luaguide-using-lua-from-vimscript* :lua~ Luaのチャンクを実行します。 > :lua require('myluamodule') < ヒアドキュメント構文を使用すると複数行に書くことができます。: > echo "Here's a bigger chunk of Lua code" lua << EOF local mod = require('mymodule') local tbl = {1, 2, 3} for k, v in ipairs(tbl) do mod.method(v) end print(tbl) EOF < Note: 各`:lua`コマンドは独自のスコープを持っており、`local`を付けた変数はコマンドの外からアクセスできません。 次の例は動作しません。: > :lua local foo = 1 :lua print(foo) " '1'ではなく'nil'が出力されます。 < Note 2: Luaの`print()`は`:echomsg`と同じように動作します。出力はメッセージ履歴に保存されます。また、`:silent`で抑制できます。 参照: - |:lua| - |:lua-heredoc| :luado~ このコマンドはカレントバッファの範囲行にLuaチャンクを実行します。範囲を指定しない場合、バッファ全体に作用します。 チャンクから`return`された文字列は、各行を置き換えるために使用されます。 次のコマンドは、カレントバッファのすべての行を`hello world`に置き換えます。: > :luado return 'hello world' < 2つの暗黙的な変数`line`と`liner`が提供されます。`line`は対象行のテキストで、`liner`はその行数です。 次のコマンドは、すべての偶数行のテキストを大文字にします。 > :luado if linenr % 2 == 0 then return line:upper() end < 参照: - |:luado| Luaファイルの読み込み~ NeovimはLuaファイルを読み込むためのEXコマンドを3つ提供しています。 - `:luafile` - `:source` - `:runtime` `:luafile`と`:source`はとてもよく似ています。: > :luafile ~/foo/bar/baz/myluafile.lua :luafile % :source ~/foo/bar/baz/myluafile.lua :source % < `:source`は範囲指定もサポートしており、スクリプトの一部を実行するのに役立ちます。: > :1,10source < `:runtime`は少し異なります。: `'runtimepath'`オプションで読み込むファイルを指定します。詳細は`:help :runtime`を参照してください。 参照: - `:help :luafile` - `:help :source` - `:help :runtime` Sourcing a lua file vs calling require()~ `require()`関数を呼ぶこととLuaファイルの読み込みの違いは何か、どちらを使うべきかを疑問に思うかもしれません。 それらには異なるユースケースがあります。: - `require()`: - Luaの組込み関数です。Luaのモジュールを読み込むのに使用します。 - `'runtimepath'`内にある`lua/`フォルダからモジュールを探します。 - どのモジュールをロードしたかを記憶し、多重に実行されるのを防ぎます。 Neovim実行中に、モジュールに含まれるコードを変更し、もう一度`require()`を実行してもモジュールは更新されません。 - `:luafile`, `:source`, `runtime`: - Exコマンドです。モジュールには対応していません。 - 以前に実行されたかどうかに関わらず実行されます。 - `:luafile`と`:source`は現在のウィンドウのディレクトリに対して相対パス・絶対パスを取ります。 - `runtime`は、`'rutimepath'`オプションを使用してファイルを探します。 `:source`や`:runtime`、ランタイムディレクトリから自動的に読み込まれたファイルも`scriptnames`と`--startuptime`に表示されます。 luaeval()~ Vim scriptの組込み関数です。文字列のLua式を評価して返します。 Luaの型は自動的にVim scriptの型に変換されます。(その逆も同様です。) > " 変数に結果を代入することができます。 let variable = luaeval('1 + 1') echo variable " 2 let concat = luaeval('"Lua".." is ".."awesome"') echo concat " 'Lua is awesome' " リストのようなテーブルはVimのリストに変換されます。 let list = luaeval('{1, 2, 3, 4}') echo list[0] " 1 echo list[1] " 2 " 注意 Luaのテーブルと違い、Vimのリストは0インデックスです。 " 辞書のようなテーブルはVimの辞書に変換されます。 let dict = luaeval('{foo = "bar", baz = "qux"}') echo dict.foo " 'bar' " bool値とnilも同様です。 echo luaeval('true') " v:true echo luaeval('nil') " v:null " Lua関数のエイリアスをVim scriptで作ることができます。 let LuaMathPow = luaeval('math.pow') echo LuaMathPow(2, 2) " 4 let LuaModuleFunction = luaeval('require("mymodule").myfunction') call LuaModuleFunction() " Vimの関数にLuaの関数を値として渡すこともできます。 lua X = function(k, v) return string.format("%s:%s", k, v) end echo map([1, 2, 3], luaeval("X")) < `luaeval()`は式にデータを渡すことのできる任意の2つ目の引数があります。Luaからは`_A`としてアクセスできます。 > echo luaeval('_A[1] + _A[2]', [1, 1]) " 2 echo luaeval('string.format("Lua is %s", _A)', 'awesome') " 'Lua is awesome' < 参照: - |luaeval()| v:lua~ Vimのグローバル変数です。Vim scriptからLuaのグローバル名前空間(`_G`: https://www.lua.org/manual/5.1/manual.html#pdf-_G )内の関数を直接呼ぶことができます。 この場合でも、Vim scriptの型はLuaの型に変換されます。逆も同様です。 > call v:lua.print('Hello from Lua!') " 'Hello from Lua!' let scream = v:lua.string.rep('A', 10) echo scream " 'AAAAAAAAAA' " How about a nice statusline? lua << EOF function _G.statusline() local filepath = '%f' local align_section = '%=' local percentage_through_file = '%p%%' return string.format( '%s%s%s', filepath, align_section, percentage_through_file ) end EOF set statusline=%!v:lua.statusline() " Also works in expression mappings lua << EOF function _G.check_back_space() local col = vim.api.nvim_win_get_cursor(0)[2] return (col == 0 or vim.api.nvim_get_current_line():sub(col, col):match('%s')) and true end EOF inoremap \ pumvisible() ? "\" : \ v:lua.check_back_space() ? "\" : \ completion#trigger_completion() " シングルクォートを使用したり、括弧を省略して、 " Luaモジュールから関数を呼び出します: call v:lua.require'module'.foo() < 参照: - |v:lua| - |v:lua-call| 警告~ この変数は関数呼び出しにのみ使用できます。次の例はエラーになります。: > " 関数のエイリアスは動作しません let LuaPrint = v:lua.print " 辞書アクセスは動作しません echo v:lua.some_global_dict['key'] " 関数を値として使用できません echo map([1, 2, 3], v:lua.global_callback) < Tips~ 設定ファイルに、`let g:vimsyn_embed = 'l'`を追加すると.vimファイル内のLuaを構文ハイライトできます。 詳細は`:h g:vimsyn_embed`を参照してください。 ============================================================================== vim名前空間 *luaguide-the-vim-namespace* NeovimはLuaからAPIを使うためのエントリーポイントとして、`vim`グーローバル変数を公開しています。 これは、拡張された標準ライブラリやさまざまなサブモジュールを提供します。 いくつかの注目すべき関数とモジュール: - `vim.inspect`: Luaオブジェクトを人間が読みやすい文字列に変換する(テーブルを調べるのに便利です。) - `vim.regex`: LuaからVimの正規表現を使う - `vim.api`: API関数を公開するモジュール(リモートプラグインで使うAPIと同じです) - `vim.ui`: プラグインから利用できる上書き可能な関数 - `vim.loop`: Neovimのイベントループ機能を公開するモジュール(LibUVを使います) - `vim.lsp`: 組込みのLSPクライアントを操作するモジュール - `vim.treesitter`: tree-sitterライブラリの機能を公開するモジュール このリストは決して包括的なリストではありません。`vim`変数で何かできるかを詳しく知りたい場合は、`:h lua-stdlib`と`:help lua-vim`が最適です。 または、`:lua print(vim.inspect(vim))`を実行してすべてのモジュールのリストを取得できます。 API関数は、`:help api-global`にあります。 Tips~ オブジェクトの中身を検査するのに毎回`print(vim.inspect(x)`を書くのは面倒です。設定にグローバルなラッパー関数を含めることは価値があるかもしれません。 (Neovim 0.7.0+では、この関数は組込み関数です。参照 |help vim.pretty_print()|): > function _G.put(...) local objects = {} for i = 1, select('#', ...) do local v = select(i, ...) table.insert(objects, vim.inspect(v)) end print(table.concat(objects, '\n')) return ... end < コードまたはコマンドラインからとても早くオブジェクトの中身を検査できます。 > put({1, 2, 3}) < > :lua put(vim.loop) < または、`:lua`コマンドでLua式の前に `=` をつけて、整列させて表示できます。(Neovim 0.7+のみ) > :lua =vim.loop 加えて、他の言語と比較して組込みのLua関数が不足している場合があります(例えば、`os.clock`はミリ秒ではなく秒数のみを返します)。 必ず、Neovim stdlib(それと`vim.fn`。詳しくは後述します。)を見てください。おそらく、探しものはそこにあります。 ============================================================================== LuaからVim scriptを使用する *luaguide-using-vimscript-from-lua* vim.api.nvim_eval()~ 文字列で与えられたVim scriptの式を評価してその値を返します。Vim scriptの型は自動的にLuaの型に変換されます。(その逆も同様です。) これは、Vim scriptの`luaeval()`と同様です。 > -- 型は正しく変換されます。 print(vim.api.nvim_eval('1 + 1')) -- 2 print(vim.inspect(vim.api.nvim_eval('[1, 2, 3]'))) -- { 1, 2, 3 } print(vim.inspect(vim.api.nvim_eval('{"foo": "bar", "baz": "qux"}'))) -- { baz = "qux", foo = "bar" } print(vim.api.nvim_eval('v:true')) -- true print(vim.api.nvim_eval('v:null')) -- nil < 警告~ `luaeval()`と違い、式にデータを渡すための暗黙的な変数`_A`を提供しません。 vim.api.nvim_exec()~ Vim scriptのチャンクを実行します。実行するソースコートを含む文字列と、コードの出力を返すかどうかを決めるbool値を受け取ります(例えば、出力を変数に格納できます)。 > local result = vim.api.nvim_exec( [[ let s:mytext = 'hello world' function! s:MyFunction(text) echo a:text endfunction call MyFunction(s:mytext) ]], true) print(result) -- 'hello world' < 警告 Neovim 0.6.0より前のバージョンでは 、`nvim_exec` はスクリプトローカル変数(`s:`)をサポートしていません。 vim.api.nvim_command()~ Exコマンドを実行します。実行するコマンドを含む文字列を受け取ります。 > vim.api.nvim_command('new') vim.api.nvim_command('wincmd H') vim.api.nvim_command('set nonumber') vim.api.nvim_command('%s/foo/bar/g') < vim.cmd()~ `vim.api.nvim_exec()`のエイリアスです。コマンドの引数のみを必要とし、`output`は常に`false`に設定されます。 > vim.cmd('buffers') vim.cmd([[ let g:multiline_list = [ \ 1, \ 2, \ 3, \ ] echo g:multiline_list ]]) Tips~ これらの関数は文字列を渡すため、多くの場合、バックスラッシュをエスケープする必要があります。: > vim.cmd('%s/\\Vfoo/bar/g') < 二重括弧の文字列はエスケープが必要ないため使いやすいです。: > vim.cmd([[%s/\Vfoo/bar/g]]) < vim.api.nvim_replace_termcodes()~ このAPI関数はターミナルコードとVimのキーコードをエスケープできます。 次のようなマッピングを見たことがあるかもしれません。: > inoremap pumvisible() ? "\" : "\" < 同じことをLuaでやると大変です。 次のようにやるかもしれません。: > function _G.smart_tab() return vim.fn.pumvisible() == 1 and [[\]] or [[\]] end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) < マッピングに `\` と `\` が挿入されているのを知るためだけに... キーコードをエスケープできるのは、Vim scriptの機能です。 `\r`, `\42` や `\x10` のような多くのプログラミング言語に共通する通常のエスケープシーケンスとは別に、 Vim scriptの `expr-quotes` (ダブルクォートで囲まれる文字列)を使用すると、 人間が読める表現のVimキーコードをエスケープします。 Luaにはそのような機能は組み込まれていません。 嬉しいことに、NeovimにはターミナルコードとキーコードをエスケープするAPI関数 `nvim_replace_termcodes()` があります。: > print(vim.api.nvim_replace_termcodes('', true, true, true)) < これは少し冗長です。再利用できるラッパーを作ると便利です。: > -- `termcodes` 専用の `t` 関数です -- この名前で呼ばなくてもいいですが、この簡潔さが便利です local function t(str) -- 必要に応じてboolean引数で調整します return vim.api.nvim_replace_termcodes(str, true, true, true) end print(t'') < 先程の例はこれで期待通りに動きます。: > local function t(str) return vim.api.nvim_replace_termcodes(str, true, true, true) end function _G.smart_tab() return vim.fn.pumvisible() == 1 and t'' or t'' end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) < `vim.keymap.set()`では、このハックは必要ありません。 `expr`が有効な場合、デフォルトで自動的に変換されます。: > vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and '' or '' end, {expr = true}) < 参照: - |keycodes| - |expr-quote| - |nvim_replace_termcodes()| ============================================================================== vimオプションを管理する *luaguide-managing-vim-options* API関数を使用する~ Neovimは、オプションの値を読み書きできるAPI関数を提供しています。 - グローバルオプション: - `vim.api.nvim_set_option()` - `vim.api.nvim_get_option()` - バッファオプション: - `vim.api.nvim_buf_set_option()` - `vim.api.nvim_buf_get_option()` - ウィンドウオプション: - `vim.api.nvim_win_set_option()` - `vim.api.nvim_win_get_option()` それらはオプションの名前と設定したい値を含む文字列を受け取ります。 boolな(`(no)number`のような)オプションは`true`か`false`のどちらかに設定する必要があります。: > vim.api.nvim_set_option('smarttab', false) print(vim.api.nvim_get_option('smarttab')) -- false < 当然ながら、文字列のオプションには文字列を設定する必要があります。: > vim.api.nvim_set_option('selection', 'exclusive') print(vim.api.nvim_get_option('selection')) -- 'exclusive' < 数値のオプションは数値を受け取ります。: > vim.api.nvim_set_option('updatetime', 3000) print(vim.api.nvim_get_option('updatetime')) -- 3000 < バッファローカルとウィンドウローカルなオプションはそれぞれの番号も必要です。(`0`を指定した場合、カレントバッファ/ウィンドウが対象になります。): > vim.api.nvim_win_set_option(0, 'number', true) vim.api.nvim_buf_set_option(10, 'shiftwidth', 4) print(vim.api.nvim_win_get_option(0, 'number')) -- true print(vim.api.nvim_buf_get_option(10, 'shiftwidth')) -- 4 < メタアクセサーを使用する~ もっと使い慣れた方法でオプションを設定したい場合、いくつかのメタアクセサーを使用できます。それらは、上記のAPI関数をラップしたものでオプションを変数のように操作できます。: - `vim.o.{option}`: `:let &{option-name}`のように動作します - `vim.go.{option}`: `:let &g:{option-name}`のように動作します - `vim.bo.{option}`: バッファローカルオプションの場合`:let &l:{option-name}`のように動作します - `vim.wo.{option}`: ウィンドウローカルオプションの場合`:let &l:{option-name}`のように動作します > vim.o.smarttab = false -- let &smarttab = v:false print(vim.o.smarttab) -- false vim.o.isfname = vim.o.isfname .. ',@-@' -- on Linux: let &isfname = &isfname .. ',@-@' print(vim.o.isfname) -- '@,48-57,/,.,-,_,+,,,#,$,%,~,=,@-@' vim.bo.shiftwidth = 4 print(vim.bo.shiftwidth) -- 4 < バッファとウィンドウの番号を指定できます。0を指定した場合、カレントバッファ/ウィンドウが使用されます。: > vim.bo[4].expandtab = true -- same as vim.api.nvim_buf_set_option(4, 'expandtab', true) vim.wo.number = true -- same as vim.api.nvim_win_set_option(0, 'number', true) < これらには、Luaで設定するのに便利なより洗練されたラッパーとして`vim.opt`があります。 `init.vim`で慣れているものと似ています。: - `vim.opt.{option}`: `:set`のように動作します - `vim.opt_global.{option}`: `:setglobal`のように動作します - `vim.opt_local.{option}`: `:setlocal`のように動作します > vim.opt.smarttab = false print(vim.opt.smarttab:get()) -- false < いくつかのオプションはLuaのテーブルを使用して設定できます。: > vim.opt.completeopt = {'menuone', 'noselect'} print(vim.inspect(vim.opt.completeopt:get())) -- { "menuone", "noselect" } < list、map、setのようなオプションのラッパーには、Vim scriptの `:set+=`, `:set^=`, `:set-=`と同じように動作するメソッドとメタメソッドが用意されています。 > vim.opt.shortmess:append({ I = true }) -- どちらも等価です: vim.opt.shortmess = vim.opt.shortmess + { I = true } vim.opt.whichwrap:remove({ 'b', 's' }) -- どちらも等価です: vim.opt.whichwrap = vim.opt.whichwrap - { 'b', 's' } < 詳細は、必ず`:help vim.opt`を参照してください。 参照: - `:help lua-vim-options` 参照: - |lua-vim-options| ============================================================================== vim内部の変数を管理する *luaguide-managing-vim-internal-variables* API関数を使用する~ オプションのように、内部変数にもAPI関数があります。 - グローバル変数 (`g:`): - `vim.api.nvim_set_var()` - `vim.api.nvim_get_var()` - `vim.api.nvim_del_var()` - バッファ変数 (`b:`): - `vim.api.nvim_buf_set_var()` - `vim.api.nvim_buf_get_var()` - `vim.api.nvim_buf_del_var()` - ウィンドウ変数 (`w:`): - `vim.api.nvim_win_set_var()` - `vim.api.nvim_win_get_var()` - `vim.api.nvim_win_del_var()` - タブ変数 (`t:`): - `vim.api.nvim_tabpage_set_var()` - `vim.api.nvim_tabpage_get_var()` - `vim.api.nvim_tabpage_del_var()` - Vimの定義済み変数 (`v:`): - `vim.api.nvim_set_vvar()` - `vim.api.nvim_get_vvar()` Vimの定義済み変数を除いて、削除できます(Vim scriptの`:unlet`と同様です)。 ローカル変数(`l:`)、スクリプト変数(`s:`)、関数の引数(`a:`)はVim script内でのみ意味があるため操作できません。 Luaには独自のスコープルールがあります。 これらの変数が不慣れな場合、`:h internal-variables`に説明があります。 これらの関数は対象の変数名と、設定したい値を含む文字列を受け取ります。 > vim.api.nvim_set_var('some_global_variable', { key1 = 'value', key2 = 300 }) print(vim.inspect(vim.api.nvim_get_var('some_global_variable'))) -- { key1 = "value", key2 = 300 } vim.api.nvim_del_var('some_global_variable') < バッファ、ウィンドウ、タブページなスコープを持つ変数はそれぞれの番号を受け取ります(0を指定した場合は現在のバッファ/ウィンドウ/タブページが使われます。)。: > vim.api.nvim_win_set_var(0, 'some_window_variable', 2500) vim.api.nvim_tab_set_var(3, 'some_tabpage_variable', 'hello world') print(vim.api.nvim_win_get_var(0, 'some_window_variable')) -- 2500 print(vim.api.nvim_buf_get_var(3, 'some_tabpage_variable')) -- 'hello world' vim.api.nvim_win_del_var(0, 'some_window_variable') vim.api.nvim_buf_del_var(3, 'some_tabpage_variable') < メタアクセサーを使用する~ 内部の変数はメタアクセサーを使用し、もっと直感的に操作できます。: - `vim.g.{name}`: グローバル変数 - `vim.b.{name}`: バッファ変数 - `vim.w.{name}`: ウィンドウ変数 - `vim.t.{name}`: タブ変数 - `vim.v.{name}`: Vimの定義済み変数 - `vim.env.{name}`: 環境変数 > vim.g.some_global_variable = { key1 = 'value', key2 = 300 } print(vim.inspect(vim.g.some_global_variable)) -- { key1 = "value", key2 = 300 } -- 特定のバッファ/ウィンドウ/タブを対象とします(Neovim 0.6+) vim.b[2].myvar = 1 < 一部の変数名には、Luaの識別子に使用できない文字が含まれている場合があります。 この構文を使用してこれらの変数を操作できます。: `vim.g['my#variable']` 変数を削除するには単に`nil`を代入します。: > vim.g.some_global_variable = nil < 警告~ 辞書の1つのキーを追加/更新/削除できません。例えば、次のVim scriptは期待通りに動きません。: > let g:variable = {} lua vim.g.variable.key = 'a' echo g:variable " {} 一時的な変数を使用する回避策があります: > let g:variable = {} lua << EOF local tmp = vim.g.variable tmp.key = 'a' vim.g.variable = tmp EOF echo g:variable " {'key': 'a'} 既知のissue: - Issue #12544: https://github.com/neovim/neovim/issues/12544 ============================================================================== Vim scriptの関数を呼び出す *luaguide-calling-vimscript-functions* vim.fn.{function}()~ `vim.fn`は、Vim script組込みの関数を呼び出せます。 型はVimとLuaとで変換されます。 > print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) print(vim.inspect(reversed_list)) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) end vim.fn.jobstart('ls', { on_stdout = print_stdout }) < ハッシュ(`#`)はLuaで有効な識別子ではないため、autoload関数は次の構文で呼び出す必要があります。: > vim.fn['my#autoload#function']() < `vim.fn`は`vim.call`と同じ動作ですが、よりLuaらしい構文を使用できます。 `vim.api.nvim_call_function`とは、Vim/Luaオブジェクトを自動で変換する点が異なります。: `vim.api.nvim_call_function`は浮動小数点数のテーブルを返しLuaのクロージャーを受け入れませんが、`vim.fn`はこれらの型を扱えます。 参照: - |vim.fn| Tips~ Neovimにはプラグインに便利な強力な組込み関数を含むライブラリがあります。 アルファベット順のリストは`:help vim-function`を参照してください。 `:help function-list`は機能別に分類されたリストです。 NeovimのAPI関数は`vim.api{..}`のように直接使用できます。 詳細は`:help api`を参照してください。 警告~ いくつかのVim関数はbool値の変わりに`1`か`0`を返します。これは、Vim scriptでは`1`は真で`0`は偽になるため問題ありません。 次のようなことが可能です。: > if has('nvim') " do something... endif < しかし、Luaで偽になるのは`false`と`nil`のみで、数値は値に関係なく常に`true`と評価されます。 明示的に`1`か`0`かをチェックする必要があります。: > if vim.fn.has('nvim') == 1 then -- do something... end < ============================================================================== マッピングを定義する *luaguide-defining-mappings* API関数~ Neovimはマッピングを設定、取得、削除するためのAPI関数を提供します。: - グローバルマッピング: - `vim.api.nvim_set_keymap()` - `vim.api.nvim_get_keymap()` - `vim.api.nvim_del_keymap()` - バッファローカルマッピング: - `vim.api.nvim_buf_set_keymap()` - `vim.api.nvim_buf_get_keymap()` - `vim.api.nvim_buf_del_keymap()` `vim.api.nvim_set_keymap()`と`vim.api.nvim_buf_set_keymap()`から始めましょう。 最初の引数には有効にするモードの名前を含む文字列を渡します。: | String value | Help page | Affected modes | Vimscript equivalent | | ---------------------- | ------------- | ---------------------------------------- | -------------------- | | `''` (an empty string) | `mapmode-nvo` | Normal, Visual, Select, Operator-pending | `:map` | | `'n'` | `mapmode-n` | Normal | `:nmap` | | `'v'` | `mapmode-v` | Visual and Select | `:vmap` | | `'s'` | `mapmode-s` | Select | `:smap` | | `'x'` | `mapmode-x` | Visual | `:xmap` | | `'o'` | `mapmode-o` | Operator-pending | `:omap` | | `'!'` | `mapmode-ic` | Insert and Command-line | `:map!` | | `'i'` | `mapmode-i` | Insert | `:imap` | | `'l'` | `mapmode-l` | Insert, Command-line, Lang-Arg | `:lmap` | | `'c'` | `mapmode-c` | Command-line | `:cmap` | | `'t'` | `mapmode-t` | Terminal | `:tmap` | 2つ目の引数は、左側のマッピングを含む文字列(マッピングで定義されたコマンドを起動するためのキー)です。 空の文字列は``と同じで、キーを無効にします。 3つ目の引数は、右側のマッピングを含む文字列(実行するコマンド)です。 最後の引数は、|:map-arguments| で定義されているbool型のオプションのテーブルです(`noremap`を含み、`buffer`を除く)。 Neovim 0.7.0から、マッピング実行時、右側のマッピングの代わりに `callback` オプションに渡した関数を呼び出せます。 バッファローカルなマッピングは、バッファ番号を引数の最初に受け取ります(`0`を指定した場合、カレントバッファです)。 > vim.api.nvim_set_keymap('n', '', ':set hlsearch!', { noremap = true, silent = true }) -- :nnoremap :set hlsearch vim.api.nvim_set_keymap('n', 'tegf', [[lua require('telescope.builtin').git_files()]], { noremap = true, silent = true }) -- :nnoremap tegf lua require('telescope.builtin').git_files() vim.api.nvim_buf_set_keymap(0, '', 'cc', 'line(".") == 1 ? "cc" : "ggcc"', { noremap = true, expr = true }) -- :noremap cc line('.') == 1 ? 'cc' : 'ggcc' vim.api.nvim_set_keymap('n', 'ex', '', { noremap = true, callback = function() print('My example') end, -- Lua関数は便利な文字列表現を持っていないため、 -- "desc" オプションを使用してマッピングの説明を記入できます。 desc = 'Prints "My example" in the message area', }) < `vim.api.nvim_get_keymap()`は、モードの省略名(上記の表を参照)を含む文字列を受け取ります。 そのモードにあるすべてのグローバルマッピングのテーブルを返します。 > print(vim.inspect(vim.api.nvim_get_keymap('n'))) -- :verbose nmap < `vim.api.nvim_buf_get_keymap()`は、最初の引数に追加でバッファ番号を受け取ります(`0`を指定した場合、カレントバッファです)。 > print(vim.inspect(vim.api.nvim_buf_get_keymap(0, 'i'))) -- :verbose imap < `vim.api.nvim_del_keymap()`は、モードと左側のマッピングを受け取ります。 > vim.api.nvim_del_keymap('n', '') -- :nunmap < この場合でも、`vim.api.nvim_buf_del_keymap()`は最初の引数にバッファ番号を受け取ります。`0`を指定した場合、カレントバッファです。 > vim.api.nvim_buf_del_keymap(0, 'i', '') -- :iunmap < vim.keymap~ :警告: このセクションで説明するAPI関数はNeovim 0.7.0+のみで使用できます。 Neovimはマッピングを設定/削除できる2つの関数を提供します: - |vim.keymap.set()| - |vim.keymap.del()| これらは、上記の類似API関数に糖類構文を追加したようなものです。 `vim.keymap.set()` は最初の引数として文字列を受け取ります。 また、複数のモードのマッピングを1度に定義するため、文字列のテーブルを受け取ることもできます: > vim.keymap.set('n', 'ex1', 'lua vim.notify("Example 1")') vim.keymap.set({'n', 'c'}, 'ex2', 'lua vim.notify("Example 2")') < 2つ目の引数は左側のマッピングです。 3つ目の引数は右側のマッピングで、文字列かLua関数を受け取れます。 > vim.keymap.set('n', 'ex1', 'echomsg "Example 1"') vim.keymap.set('n', 'ex2', function() print("Example 2") end) vim.keymap.set('n', 'pl1', require('plugin').plugin_action) -- モジュールの読み込みによる起動コストを避けるため、 -- マッピングを呼び出したときにモジュールの遅延読みこみができるように関数でラップすることができます。: vim.keymap.set('n', 'pl2', function() require('plugin').plugin_action() end) < 4つ目の引数)省略可能)はオプションのテーブルで、 `vim.api.nvim_set_keymap` に渡されるオプションに対応しており、いくつか追加項目があります (|vim.keymap.set()|にhttps://neovim.io/doc/user/lua.html#vim.keymap.setに一覧があります)。 > vim.keymap.set('n', 'ex1', 'echomsg "Example 1"', {buffer = true}) vim.keymap.set('n', 'ex2', function() print('Example 2') end, {desc = 'Prints "Example 2" to the message area'}) < 文字列を使用して定義するキーマップとLua関数で定義したキーマップは違います。 通常の`:nmap ex1`のようなキーマップ情報を表示する方法では、 `Lua function` とだけ表示され有用な情報（関数の内容自体）が表示されません。 キーマップの動作を説明する`desc`キーを追加するのを推奨します。 これはプラグインのマッピングのドキュメント化に特に重要です。 ユーザーはキーマップの使用方法をより簡単に理解できます。 このAPIが面白いところとして、Vimのマッピングの歴史的な癖をいくつか解消しています。 - `rhs` が `` マッピングである場合以外、デフォルトで `noremap` です。 このため、マッピングが再帰的であるかを考える必要はあまりないです。 > vim.keymap.set('n', 'test1', 'echo "test"') -- :nnoremap test echo "test" -- マッピングを再帰的に行ないたい場合は、 `remap` オプションを `true` にします vim.keymap.set('n', '>', ']', {remap = true}) -- :nmap > ] -- マッピングは再帰的でないと機能しませんが、 vim.keymap.set() は自動的に処理します vim.keymap.set('n', 'plug', '(plugin)') -- :nmap plug (plugin) < - `expr` マッピングが有効なら、 Lua関数が返す文字列に対して `nvim_replace_termcodes()` が自動的に適用されます: > vim.keymap.set('i', '', function() return vim.fn.pumvisible == 1 and '' or '' end, {expr = true}) < 参照: - `:help recursive_mapping`: https://neovim.io/doc/user/map.html#recursive_mapping `vim.keymap.del()` も同じように機能しますが、マッピングを削除します: > vim.keymap.del('n', 'ex1') vim.keymap.del({'n', 'c'}, 'ex2', {buffer = true}) < ============================================================================== ユーザーコマンドを定義する *luaguide-defining-user-commands* WARNING: このセクションで説明するAPI関数はNeovim 0.7.0+のみで使用できます。 Neovimはユーザーコマンドを作成するAPI関数を提供します。 - Global user commands: - |nvim_create_user_command()| - |nvim_del_user_command()| - Buffer-local user commands: - |nvim_buf_create_user_command()| - |nvim_buf_del_user_command()| まず `vim.api.nvim_create_user_command()` から始めます 最初の引数はコマンドの名前です(名前は大文字で始める必要があります)。 2つめの引数はコマンドが呼びだされたときに実行するコードです。次のどちらかでコードを指定できます: 文字列(この場合、VimScriptとして実行されます)。 `:commands` のように、``, `` などのエスケープシーケンスを使用できます。 > vim.api.nvim_create_user_command('Upper', 'echo toupper()', { nargs = 1 }) -- :command! -nargs=1 Upper echo toupper() vim.cmd('Upper hello world') -- prints "HELLO WORLD" < もしくは、Lua関数。 通常のエスケープシーケンスによって提供されるデータを含む、 辞書のようなテーブルを受け取ります (利用できるキーのリストは|nvim_create_user_command()|で確認できます)。 > vim.api.nvim_create_user_command( 'Upper', function(opts) print(string.upper(opts.args)) end, { nargs = 1 } ) < 3つめの引数はコマンドの属性をテーブルとして渡せます(|command-attributes|を参照)。 `vim.api.nvim_buf_create_user_command()`を使用すればバッファローカルなユーザーコマンドを定義できるため、 `-buffer`は有効な属性ではありません。 追加された2つの属性: - `desc`はLuaのコールバックとして定義されたコマンドに対して`:command {cmd}`を実行したときの表示内容を制御できます。 キーマップと同様、Lua関数として定義するコマンドには `desc`キーを追加するのを推奨します。 - `force`は`:command!`を呼び出すのと同じで、同じ名前のユーザーコマンドが既に存在する場合、そのコマンドを置き換えます。 Vimscriptとは異なり、デフォルトでtrueです。 `-complete`属性は|:command-complete|に記載されている属性に加え、Lua関数を取ることができます。 > vim.api.nvim_create_user_command('Upper', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) -- return completion candidates as a list-like table return { 'foo', 'bar', 'baz' } end, }) < バッファローカルなユーザーコマンドも第1引数にバッファ番号を受け取ります。 現在のバッファ用のコマンドを定義することができる`-buffer`より、これは便利です。 > vim.api.nvim_buf_create_user_command(4, 'Upper', function() end, {}) < `vim.api.nvim_del_user_command()` はコマンド名を受け取ります。 > vim.api.nvim_del_user_command('Upper') -- :delcommand Upper < ここでも、`vim.api.nvim_buf_del_user_command()`はバッファ番号を第1引数として受け取り、`0`は現在のバッファを表します。 > vim.api.nvim_buf_del_user_command(4, 'Upper') < 参照: - |nvim_create_user_command()| - |40.2| - |command-attributes| 警告~ `-complete=custom`属性は自動的に補完候補をフィルタリングし、 ワイルドカード(|wildcard|)をサポートする機能を組み込みます: > function! s:completion_function(ArgLead, CmdLine, CursorPos) abort return join([ \ 'strawberry', \ 'star', \ 'stellar', \ ], "\n") endfunction command! -nargs=1 -complete=custom,s:completion_function Test echo " `:Test st[ae]` と入力すると "star" と "stellar" を返します < `complete` にLua関数に渡すと、ユーザーにフィルタ方法を任せる`customlist`のような動作をします。 > vim.api.nvim_create_user_command('Test', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) return { 'strawberry', 'star', 'stellar', } end, }) -- 候補リストをフィルタしてないので `:Test z` と入力すると全ての補完候補を返します < ============================================================================== オートコマンドを定義する *luaguide-defining-autocommands* (この章は現在作成中です) Neovim 0.7.0はオートコマンド用のAPI関数を持っています。詳細は|api-autocmd|を参照してください。 - Pull request #14661: https://github.com/neovim/neovim/pull/14661 (lua: autocmds take 2) ============================================================================== ハイライトを定義する *luaguide-defining-syntax-highlights* (この章は現在作成中です) Neovim 0.7.0はハイライトグループ用のAPI関数を持っています。 参照: - |nvim_set_hl()| - |nvim_get_hl_by_id()| - |nvim_get_hl_by_name()| ============================================================================== 一般的なTipsと推奨 *luaguide-general-tips-and-recommendations* キャッシュされたモジュールのリロード~ Luaでは、`require()`関数がモジュールをキャッシュします。 これはパフォーマンスには良いですが、後から`require()`を呼んでもモジュールは更新されないため少し面倒です。 特定のモジュールのキャッシュを更新する場合、`package.loaded`グローバルテーブルを変更する必要があります。: > package.loaded['modname'] = nil require('modname') -- 新しい'modname'モジュールを読み込みます < nvim-lua/plenary.nvim: https://github.com/nvim-lua/plenary.nvim には、これを行う関数: https://github.com/nvim-lua/plenary.nvim/blob/master/lua/plenary/reload.lua があります。 Luaの文字列をパディングしないでください!~ 二重括弧の文字列を使用するとき、パディングの誘惑に負けないでください! スペースを無視するときは問題ないですが、スペースが重要な意味を持つときはデバックが困難な問題の原因になる可能性があります。: > vim.api.nvim_set_keymap('n', 'f', [[ call foo() ]], {noremap = true}) < 上記の例では、`f`は`call foo()`ではなく`call foo()`にマッピングされます。 Vim script <--> Lua 型変換の注意~ 変数を変換するとコピーが作られます:~ VimからLua、LuaからVimのオブジェクトの参照を直接操作できません。 例えば、Vim scriptの`map()`は変数をその場で変更します(破壊的)。 > let s:list = [1, 2, 3] let s:newlist = map(s:list, {_, v -> v * 2}) echo s:list " [2, 4, 6] echo s:newlist " [2, 4, 6] echo s:list is# s:newlist " 1 < Luaからこの関数を使用すると、代りにコピーが作られます > local tbl = {1, 2, 3} local newtbl = vim.fn.map(tbl, function(_, v) return v * 2 end) print(vim.inspect(tbl)) -- { 1, 2, 3 } print(vim.inspect(newtbl)) -- { 2, 4, 6 } print(tbl == newtbl) -- false < 変換を常にできるとは限りません~ これは主に関数とテーブルに影響します。 Luaのリストと辞書が混在するテーブルは変換できません。 > print(vim.fn.count({1, 1, number = 1}, 1)) -- E5100: Cannot convert given lua table: table should either have a sequence of positive integer keys or contain only string keys < Luaで`vim.fn`を使用してVim関数を呼べますが、それらの参照を保持できません。 それは不測の動作の原因になります。: > local FugitiveHead = vim.fn.funcref('FugitiveHead') print(FugitiveHead) -- vim.NIL vim.cmd("let g:test_dict = {'test_lambda': {-> 1}}") print(vim.g.test_dict.test_lambda) -- nil print(vim.inspect(vim.g.test_dict)) -- {} < Luaの関数をVimの関数に渡せますが、Vimの変数に格納できません。 (Neovim 0.7.0+で修正されて、格納できるようになりました。) > -- This works: vim.fn.jobstart({'ls'}, { on_stdout = function(chan_id, data, name) print(vim.inspect(data)) end }) -- This doesn't: vim.g.test_dict = {test_lambda = function() return 1 end} -- Error: Cannot convert given lua type < ただし、Vim scriptから`luaeval()`を使用して同じことをすると**動作します**。: > let g:test_dict = {'test_lambda': luaeval('function() return 1 end')} echo g:test_dict " {'test_lambda': function('4714')} < Vim booleans~ Vim scriptの一般的なパターンではbool値の代わりに`1`と`0`を使用します。 実際、Vimにはバージョン7.4.1154まで区別されたbool型がありませんでした。 Luaのbool値は数値ではなく、Vim scriptの実際のbool値に変換されます。: > lua vim.g.lua_true = true echo g:lua_true " v:true lua vim.g.lua_false = false echo g:lua_false " v:false < リンターと言語サーバーの設定~ Luaのプロジェクトでリンターや言語サーバーを使用して、診断と自動補完を利用している場合、Neovim固有の設定が必要になる場合があります。人気のあるツールの推奨設定は次のとおりです。: luacheck~ 次の設定を `~/.luacheckrc` もしくは `$XDG_CONFIG_HOME/luacheck/.luacheckrc` に配置すれば、 luacheck: https://github.com/mpeterv/luacheck/ でvimモジュールを認識できます。: > globals = { "vim", } < 言語サーバーの Alloyed/lua-lsp: https://github.com/Alloyed/lua-lsp/ は `luacheck` を使用してリンティングを提供し、同じファイルを読み込みます。 `luacheck` の設定方法の詳細は ドキュメント: https://luacheck.readthedocs.io/en/stable/config.html を参照してください。 sumneko/lua-language-server~ nvim-lspconfig: https://github.com/neovim/nvim-lspconfig/ リポジトリに sumneko/lua-language-serverの設定方法: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sumneko_lua があります。例は組込みのLSPクライアントを使っていますが、他のLSPクライアントでも同じ設定である必要があります。 sumneko/lua-language-server: https://github.com/sumneko/lua-language-server/ の設定方法の詳細は "Setting": https://github.com/sumneko/lua-language-server/wiki/Setting を見てください。 coc.nvim~ coc.nvim: https://github.com/neoclide/coc.nvim/ の補完ソースである rafcamlet/coc-nvim-lua: https://github.com/rafcamlet/coc-nvim-lua/ はNeovim stdlibの項目を提供しています。 Luaコードのデバッグ~ 別のNeovimインスタンスで実行しているLuaコードを jbyuki/one-small-step-for-vimkind: https://github.com/jbyuki/one-small-step-for-vimkind でデバッグできます。 このプラグインは Debug Adapter Protocol: https://microsoft.github.io/debug-adapter-protocol/ を使用しています。 デバッグアダプターに接続するには、 mfussenegger/nvim-dap: https://github.com/mfussenegger/nvim-dap/ や puremourning/vimspector: https://github.com/puremourning/vimspector/ のようなDAPクライアントが必要です。 Luaマッピング/コマンド/オートコマンドのデバッグ~ マッピング/コマンド/オートコマンドが定義されている位置を `:verbose` コマンドで確認できます: > :verbose map m < > n m_ * echo 'example' Last set from ~/.config/nvim/init.vim line 26 < デフォルトでは、Luaのパフォーマンス上の理由でこの機能は無効です。 Neovim起動時にverboseのレベルが0より上なら、この機能を有効にできます: > nvim -V1 < 参照: - |'verbose'| - |-V| - neovim/neovim#15079: https://github.com/neovim/neovim/pull/15079 Luaコードのテスト~ - plenary.nvim: test harness: https://github.com/nvim-lua/plenary.nvim/#plenarytest_harness - notomo/vusted: https://github.com/notomo/vusted Luarocksパッケージを使用する~ wbthomason/packer.nvim: https://github.com/wbthomason/packer.nvim はLuarocksパッケージをサポートしています。 使い方はREADME: https://github.com/wbthomason/packer.nvim/#luarocks-support にあります。 ============================================================================== その他 *luaguide-miscellaneous* vim.loop~ `vim.loop`はLibUV APIを公開するモジュールです。いくつかのリソース: - Official documentation for LibUV: https://docs.libuv.org/en/v1.x/ - Luv documentation: https://github.com/luvit/luv/blob/master/docs.md - teukka.tech - Using LibUV in Neovim: https://teukka.tech/posts/2020-01-07-vimloop/ 参照: - |vim.loop| vim.lsp~ `vim.lsp`は組込みのLSPクライアントを操作するためのモジュールです。 neovim/nvim-lspconfig: https://github.com/neovim/nvim-lspconfig/ は有名なLanguage Serverの設定集です。 クライアントの動作は"lsp-handlers"を使用して設定できます。詳細はこちら: - |lsp-handler| - neovim/neovim#12655: https://github.com/neovim/neovim/pull/12655 - How to migrate from diagnostic-nvim: https://github.com/nvim-lua/diagnostic-nvim/issues/73#issue-737897078 LSPクライアントを利用したプラグインも見たいかもしれません。: https://github.com/rockerBOO/awesome-neovim#lsp 参照: - |lsp| vim.treesitter~ `vim.treesitter`はNeovim内の Tree-sitter: https://tree-sitter.github.io/tree-sitter/ ライブラリを操作するためのモジュールです。 Tree-sitterについてもっと知りたいなら、この プレゼン 38:37 : https://www.youtube.com/watch?v=Jes3bD6P0To に興味があるかもしれません。 nvim-treesitter: https://github.com/nvim-treesitter/ オリジネーションは、ライブラリを利用して様々なプラグインをホストしています。 参照: - |lua-treesitter| トランスパイラ~ Luaを使用する利点の1つは実際にLuaを書く必要がないことです！利用できるトランスパイラはたくさんあります。 - Moonscript: https://moonscript.org/ おそらく、最も知られているLuaのトランスパイラです。クラス、リスト内包表記、関数リテラルなどの便利な機能を多数追加します。 svermeulen/nvim-moonmaker: https://github.com/svermeulen/nvim-moonmaker はNeovimのプラグインと設定をMoonscriptで直接書けるようにします。 - Fennel: https://fennel-lang.org/ lispをLuaにコンパイルします。 Olical/aniseed: https://github.com/Olical/aniseed または、Hotpot: https://github.com/rktjmp/hotpot.nvim を使用するとNeovimのプラグインと設定を書くことができます。 さらに、 Olical/conjure: https://github.com/Olical/conjure は対話的な開発環境を提供します 他の言語の中で 。 - Teal: https://github.com/teal-language/tl Tealの名前の由来はTL(typed lua)の発音からです。 まさにその通りで、強力な型をLuaに追加し、それ以外は標準のLuaの構文に近づけています。 nvim-teal-maker https://github.com/svermeulen/nvim-teal-maker プラグインを使用して、 TealでNeovimプラグインや設定ファイルを書けます。 その他の興味深いプロジェクト: - TypeScriptToLua/TypeScriptToLua: https://github.com/TypeScriptToLua/TypeScriptToLua - Haxe: https://haxe.org/ - SwadicalRag/wasm2lua: https://github.com/SwadicalRag/wasm2lua - hengestone/lua-languages: https://github.com/hengestone/lua-languages vim:tw=78:ts=8:noet:ft=help:norl: ================================================ FILE: doc/nvim-lua-guide.txt ================================================ *nvim-lua-guide.txt* Getting started using Lua in Neovim ============================================================================== INTRODUCTION *luaguide-introduction* The integration of Lua: https://www.youtube.com/watch?v=IP3J56sKtn0 as a first-class language inside Neovim: https://github.com/neovim/neovim/wiki/FAQ#why-embed-lua-instead-of-x is shaping up to be one of its killer features. However, the amount of teaching material for learning how to write plugins in Lua is not as large as what you would find for writing them in Vimscript. This is an attempt at providing some basic information to get people started. This guide assumes you are using at least version 0.5 of Neovim. Learning Lua~ If you are not already familiar with the language, there are plenty of resources to get started: - The Learn X in Y minutes page about Lua: https://learnxinyminutes.com/docs/lua/ should give you a quick overview of the basics - This guide: https://github.com/medwatt/Notes/blob/main/Lua/Lua_Quick_Guide.ipynb is also a good resource for getting started quickly - If videos are more to your liking, Derek Banas has a 1-hour tutorial on the language: https://www.youtube.com/watch?v=iMacxZQMPXs - Want something a little more interactive with runnable examples? Try the LuaScript tutorial: https://www.luascript.dev/learn - The lua-users wiki: http://lua-users.org/wiki/LuaDirectory is full of useful information on all kinds of Lua-related topics - The official reference manual for Lua: https://www.lua.org/manual/5.1/ should give you the most comprehensive tour of the language exists as a Vimdoc plugin if you want to read it from the comfort of your editor: milisims/nvim-luaref: https://github.com/milisims/nvim-luaref It should also be noted that Lua is a very clean and simple language. It is easy to learn, especially if you have experience with similar scripting languages like JavaScript. You may already know more Lua than you realise! Note: the version of Lua that Neovim embeds is LuaJIT: https://staff.fnwi.uva.nl/h.vandermeer/docs/lua/luajit/luajit_intro.html 2.1.0, which maintains compatibility with Lua 5.1. Existing tutorials for writing Lua in Neovim~ A few tutorials have already been written to help people write plugins in Lua. Some of them helped quite a bit when writing this guide. Many thanks to their authors. - teukka.tech - From init.vim to init.lua: https://teukka.tech/luanvim.html - dev.to - How to write neovim plugins in Lua: https://dev.to/2nit/how-to-write-neovim-plugins-in-lua-5cca - dev.to - How to make UI for neovim plugins in Lua: https://dev.to/2nit/how-to-make-ui-for-neovim-plugins-in-lua-3b6e - ms-jpq - Neovim Async Tutorial: https://github.com/ms-jpq/neovim-async-tutorial - oroques.dev - Neovim 0.5 features and the switch to init.lua: https://oroques.dev/notes/neovim-init/ - Building A Vim Statusline from Scratch - jdhao's blog: https://jdhao.github.io/2019/11/03/vim_custom_statusline/ - Configuring Neovim using Lua: https://icyphox.sh/blog/nvim-lua/ - Devlog | Everything you need to know to configure neovim using lua: https://vonheikemen.github.io/devlog/tools/configuring-neovim-using-lua/ Companion plugins~ - Vimpeccable: https://github.com/svermeulen/vimpeccable - Plugin to help write your .vimrc in Lua - plenary.nvim: https://github.com/nvim-lua/plenary.nvim - All the lua functions I don't want to write twice - popup.nvim: https://github.com/nvim-lua/popup.nvim - An implementation of the Popup API from vim in Neovim - nvim_utils: https://github.com/norcalli/nvim_utils - nvim-luadev: https://github.com/bfredl/nvim-luadev - REPL/debug console for nvim lua plugins - nvim-luapad: https://github.com/rafcamlet/nvim-luapad - Interactive real time neovim scratchpad for embedded lua engine - nlua.nvim: https://github.com/tjdevries/nlua.nvim - Lua Development for Neovim - BetterLua.vim: https://github.com/euclidianAce/BetterLua.vim - Better Lua syntax highlighting in Vim/NeoVim ============================================================================== WHERE TO PUT LUA FILES *luaguide-where-to-put-lua-files* init.lua~ Neovim supports loading an `init.lua` file for configuration instead of the usual `init.vim`. Note: `init.lua` is of course _completely_ optional. Support for `init.vim` is not going away and is still a valid option for configuration. Do keep in mind that some features are not 100% exposed to Lua yet. See also: - |config| Modules~ Lua modules are found inside a `lua/` folder in your `'runtimepath'` (for most users, this will mean `~/.config/nvim/lua` on \*nix systems and `~/AppData/Local/nvim/lua` on Windows). You can `require()` files in this folder as Lua modules. Let's take the following folder structure as an example: > 📂 ~/.config/nvim ├── 📁 after ├── 📁 ftplugin ├── 📂 lua │ ├── 🌑 myluamodule.lua │ └── 📂 other_modules │ ├── 🌑 anothermodule.lua │ └── 🌑 init.lua ├── 📁 pack ├── 📁 plugin ├── 📁 syntax └── 🇻 init.vim < The following Lua code will load `myluamodule.lua`: > require('myluamodule') < Notice the absence of a `.lua` extension. Similarly, loading `other_modules/anothermodule.lua` is done like so: > require('other_modules.anothermodule') -- or require('other_modules/anothermodule') < Path separators are denoted by either a dot `.` or a slash `/`. A folder containing an `init.lua` file can be required directly, without having to specify the name of the file. > require('other_modules') -- loads other_modules/init.lua < Requiring a nonexistent module or a module which contains syntax errors aborts the currently executing script. `pcall()` may be used to prevent errors. > local ok, _ = pcall(require, 'module_with_error') if not ok then -- not loaded end < See also: - |lua-require| Tips~ Several Lua plugins might have identical filenames in their `lua/` folder. This could lead to namespace clashes. If two different plugins have a `lua/main.lua` file, then doing `require('main')` is ambiguous: which file do we want to source? It might be a good idea to namespace your config or your plugin with a top-level folder, like so: `lua/plugin_name/main.lua` Runtime files~ Much like Vimscript files, Lua files can be loaded automatically from special folders in your `runtimepath`. Currently, the following folders are supported: - `colors/` - `compiler/` - `ftplugin/` - `ftdetect/` - `indent/` - `plugin/` - `syntax/` Note: in a runtime directory, all `*.vim` files are sourced before `*.lua` files. See also: - |'runtimepath'| - |load-plugins| Tips~ Since runtime files aren't based on the Lua module system, two plugins can have a `plugin/main.lua` file without it being an issue. ============================================================================== USING LUA FROM VIMSCRIPT *luaguide-using-lua-from-vimscript* :lua~ This command executes a chunk of Lua code. > :lua require('myluamodule') < Multi-line scripts are possible using heredoc syntax: > echo "Here's a bigger chunk of Lua code" lua << EOF local mod = require('mymodule') local tbl = {1, 2, 3} for k, v in ipairs(tbl) do mod.method(v) end print(tbl) EOF < Note: each `:lua` command has its own scope and variables declared with the `local` keyword are not accessible outside of the command. This won't work: > :lua local foo = 1 :lua print(foo) " prints 'nil' instead of '1' < Note 2: the `print()` function in Lua behaves similarly to the `:echomsg` command. Its output is saved in the message-history and can be suppressed by the `:silent` command. See also: - |:lua| - |:lua-heredoc| :luado~ This command executes a chunk of Lua code that acts on a range of lines in the current buffer. If no range is specified, the whole buffer is used instead. Whatever string is `return`ed from the chunk is used to determine what each line should be replaced with. The following command would replace every line in the current buffer with the text `hello world`: > :luado return 'hello world' < Two implicit `line` and `linenr` variables are also provided. `line` is the text of the line being iterated upon whereas `linenr` is its number. The following command would make every line whose number is divisible by 2 uppercase: > :luado if linenr % 2 == 0 then return line:upper() end < See also: - |:luado| Sourcing Lua files~ Neovim provides 3 Ex commands to source Lua files - `:luafile` - `:source` - `:runtime` `:luafile` and `:source` are very similar: > :luafile ~/foo/bar/baz/myluafile.lua :luafile % :source ~/foo/bar/baz/myluafile.lua :source % < `:source` also supports ranges, which can be useful to only execute part of a script: > :1,10source < `:runtime` is a little different: it uses the `'runtimepath'` option to determine which files to source. See |:runtime| for more details. See also: - |:luafile| - |:source| - |:runtime| Sourcing a lua file vs calling require():~ You might be wondering what the difference between calling the `require()` function and sourcing a Lua file is and whether you should prefer one way over the other. They have different use cases: - `require()`: - is a built-in Lua function. It allows you to take advantage of Lua's module system - searches for modules in `lua/` folders in your `'runtimepath'` - keeps track of what modules have been loaded and prevents a script from being parsed and executed a second time. If you change the file containing the code for a module and try to `require()` it a second time while Neovim is running, the module will not actually update - `:luafile`, `:source` and `:runtime`: - are Ex commands. They do not support modules - execute the contents of a script regardless of whether it has been executed before - `:luafile` and `:source` take a path that is either absolute or relative to the working directory of the current window - `:runtime` uses the `'runtimepath'` option to find files Files sourced via `:source`, `:runtime` or automatically from runtime directories will also show up in `:scriptnames` and `--startuptime` luaeval()~ This built-in Vimscript function evaluates a Lua expression string and returns its value. Lua data types are automatically converted to Vimscript types (and vice versa). > " You can store the result in a variable let variable = luaeval('1 + 1') echo variable " 2 let concat = luaeval('"Lua".." is ".."awesome"') echo concat " 'Lua is awesome' " List-like tables are converted to Vim lists let list = luaeval('{1, 2, 3, 4}') echo list[0] " 1 echo list[1] " 2 " Note that unlike Lua tables, Vim lists are 0-indexed " Dict-like tables are converted to Vim dictionaries let dict = luaeval('{foo = "bar", baz = "qux"}') echo dict.foo " 'bar' " Same thing for booleans and nil echo luaeval('true') " v:true echo luaeval('nil') " v:null " You can create Vimscript aliases for Lua functions let LuaMathPow = luaeval('math.pow') echo LuaMathPow(2, 2) " 4 let LuaModuleFunction = luaeval('require("mymodule").myfunction') call LuaModuleFunction() " It is also possible to pass Lua functions as values to Vim functions lua X = function(k, v) return string.format("%s:%s", k, v) end echo map([1, 2, 3], luaeval("X")) < `luaeval()` takes an optional second argument that allows you to pass data to the expression. You can then access that data from Lua using the magic global `_A`: > echo luaeval('_A[1] + _A[2]', [1, 1]) " 2 echo luaeval('string.format("Lua is %s", _A)', 'awesome') " 'Lua is awesome' < See also: - |luaeval()| v:lua~ This global Vim variable allows you to call Lua functions in the global namespace `_G`: https://www.lua.org/manual/5.1/manual.html#pdf-_G directly from Vimscript. Again, Vim data types are converted to Lua types and vice versa. > call v:lua.print('Hello from Lua!') " 'Hello from Lua!' let scream = v:lua.string.rep('A', 10) echo scream " 'AAAAAAAAAA' " How about a nice statusline? lua << EOF function _G.statusline() local filepath = '%f' local align_section = '%=' local percentage_through_file = '%p%%' return string.format( '%s%s%s', filepath, align_section, percentage_through_file ) end EOF set statusline=%!v:lua.statusline() " Also works in expression mappings lua << EOF function _G.check_back_space() local col = vim.api.nvim_win_get_cursor(0)[2] return (col == 0 or vim.api.nvim_get_current_line():sub(col, col):match('%s')) and true end EOF inoremap \ pumvisible() ? "\" : \ v:lua.check_back_space() ? "\" : \ completion#trigger_completion() " Call a function from a Lua module by using single quotes and omitting parentheses: call v:lua.require'module'.foo() < See also: - |v:lua| - |v:lua-call| Caveats~ This variable can only be used to call functions. The following will always throw an error: > " Aliasing functions doesn't work let LuaPrint = v:lua.print " Accessing dictionaries doesn't work echo v:lua.some_global_dict['key'] " Using a function as a value doesn't work echo map([1, 2, 3], v:lua.global_callback) < Tips~ You can get Lua syntax highlighting inside .vim files by putting `let g:vimsyn_embed = 'l'` in your configuration file. See |g:vimsyn_embed| for more on this option. ============================================================================== THE VIM NAMESPACE *luaguide-the-vim-namespace* Neovim exposes a global `vim` variable which serves as an entry point to interact with its APIs from Lua. It provides users with an extended "standard library" of functions as well as various sub-modules. Some notable functions and modules include: - `vim.inspect`: transform Lua objects into human-readable strings (useful for inspecting tables) - `vim.regex`: use Vim regexes from Lua - `vim.api`: module that exposes API functions (the same API used by remote plugins) - `vim.ui`: overridable UI functions that can be leveraged by plugins - `vim.loop`: module that exposes the functionality of Neovim's event-loop (using LibUV) - `vim.lsp`: module that controls the built-in LSP client - `vim.treesitter`: module that exposes the functionality of the tree-sitter library This list is by no means comprehensive. If you wish to know more about what's made available by the `vim` variable, |lua-stdlib| and |lua-vim| are the way to go. Alternatively, you can do `:lua print(vim.inspect(vim))` to get a list of every module. API functions are documented under |api-global|. Tips~ Writing `print(vim.inspect(x))` every time you want to inspect the contents of an object can get pretty tedious. It might be worthwhile to have a global wrapper function somewhere in your configuration (in Neovim 0.7.0+, this function is built-in, see |vim.pretty_print()|: > function _G.put(...) local objects = {} for i = 1, select('#', ...) do local v = select(i, ...) table.insert(objects, vim.inspect(v)) end print(table.concat(objects, '\n')) return ... end < You can then inspect the contents of an object very quickly in your code or from the command-line: > put({1, 2, 3}) < > :lua put(vim.loop) < Alternatively, you can use the `:lua` command to pretty-print a Lua expression by prefixing it with `=` (Neovim 0.7+ only): > :lua =vim.loop < Additionally, you may find that built-in Lua functions are sometimes lacking compared to what you would find in other languages (for example `os.clock()` only returns a value in seconds, not milliseconds). Be sure to look at the Neovim stdlib (and `vim.fn`, more on that later), it probably has what you're looking for. ============================================================================== USING VIMSCRIPT FROM LUA *luaguide-using-vimscript-from-lua* vim.api.nvim_eval()~ This function evaluates a Vimscript expression string and returns its value. Vimscript data types are automatically converted to Lua types (and vice versa). It is the Lua equivalent of the `luaeval()` function in Vimscript > -- Data types are converted correctly print(vim.api.nvim_eval('1 + 1')) -- 2 print(vim.inspect(vim.api.nvim_eval('[1, 2, 3]'))) -- { 1, 2, 3 } print(vim.inspect(vim.api.nvim_eval('{"foo": "bar", "baz": "qux"}'))) -- { baz = "qux", foo = "bar" } print(vim.api.nvim_eval('v:true')) -- true print(vim.api.nvim_eval('v:null')) -- nil < Caveats~ Unlike `luaeval()`, `vim.api.nvim_eval()` does not provide an implicit `_A` variable to pass data to the expression. vim.api.nvim_exec()~ This function evaluates a chunk of Vimscript code. It takes in a string containing the source code to execute and a boolean to determine whether the output of the code should be returned by the function (you can then store the output in a variable, for example). > local result = vim.api.nvim_exec( [[ let s:mytext = 'hello world' function! s:MyFunction(text) echo a:text endfunction call s:MyFunction(s:mytext) ]], true) print(result) -- 'hello world' < Caveats~ `nvim_exec` does not support script-local variables (`s:`) prior to Neovim 0.6.0 vim.api.nvim_command()~ This function executes an ex command. It takes in a string containing the command to execute. > vim.api.nvim_command('new') vim.api.nvim_command('wincmd H') vim.api.nvim_command('set nonumber') vim.api.nvim_command('%s/foo/bar/g') < vim.cmd()~ Alias for `vim.api.nvim_exec()`. Only the command argument is needed, `output` is always set to `false`. > vim.cmd('buffers') vim.cmd([[ let g:multiline_list = [ \ 1, \ 2, \ 3, \ ] echo g:multiline_list ]]) < Tips~ Since you have to pass strings to these functions, you often end up having to escape backslashes: > vim.cmd('%s/\\Vfoo/bar/g') < Double bracketed strings are easier to use as they do not require escaping characters: > vim.cmd([[%s/\Vfoo/bar/g]]) < vim.api.nvim_replace_termcodes()~ This API function allows you to escape terminal codes and Vim keycodes. You may have come across mappings like this one: > inoremap pumvisible() ? "\" : "\" < Trying to do the same in Lua can prove to be a challenge. You might be tempted to do it like this: > function _G.smart_tab() return vim.fn.pumvisible() == 1 and [[\]] or [[\]] end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) < only to find out that the mapping inserts `\` and `\` literally... Being able to escape keycodes is actually a Vimscript feature. Aside from the usual escape sequences like `\r`, `\42` or `\x10` that are common to many programming languages, Vimscript `expr-quotes` (strings surrounded with double quotes) allow you to escape the human-readable representation of Vim keycodes. Lua doesn't have such a feature built-in. Fortunately, Neovim has an API function for escaping terminal codes and keycodes: `nvim_replace_termcodes()` > print(vim.api.nvim_replace_termcodes('', true, true, true)) < This is a little verbose. Making a reusable wrapper can help: > -- The function is called `t` for `termcodes`. -- You don't have to call it that, but I find the terseness convenient local function t(str) -- Adjust boolean arguments as needed return vim.api.nvim_replace_termcodes(str, true, true, true) end print(t'') < Coming back to our earlier example, this should now work as expected: > local function t(str) return vim.api.nvim_replace_termcodes(str, true, true, true) end function _G.smart_tab() return vim.fn.pumvisible() == 1 and t'' or t'' end vim.api.nvim_set_keymap('i', '', 'v:lua.smart_tab()', {expr = true, noremap = true}) < This is not necessary with `vim.keymap.set()` as it automatically transforms vim keycodes returned by Lua functions in `expr` mappings by default: > vim.keymap.set('i', '', function() return vim.fn.pumvisible() == 1 and '' or '' end, {expr = true}) < See also: - |keycodes| - |expr-quote| - |nvim_replace_termcodes()| ============================================================================== MANAGING VIM OPTIONS *luaguide-managing-vim-options* Using api functions~ Neovim provides a set of API functions to either set an option or get its current value: - Global options: - |nvim_set_option()| - |nvim_get_option()| - Buffer-local options: - |nvim_buf_set_option()| - |nvim_buf_get_option()| - Window-local options: - |nvim_win_set_option()| - |nvim_win_get_option()| They take a string containing the name of the option to set/get as well as the value you want to set it to. Boolean options (like `(no)number`) have to be set to either `true` or `false`: > vim.api.nvim_set_option('smarttab', false) print(vim.api.nvim_get_option('smarttab')) -- false < Unsurprisingly, string options have to be set to a string: > vim.api.nvim_set_option('selection', 'exclusive') print(vim.api.nvim_get_option('selection')) -- 'exclusive' < Number options accept a number: > vim.api.nvim_set_option('updatetime', 3000) print(vim.api.nvim_get_option('updatetime')) -- 3000 < Buffer-local and window-local options also need a buffer number or a window number (using `0` will set/get the option for the current buffer/window): > vim.api.nvim_win_set_option(0, 'number', true) vim.api.nvim_buf_set_option(10, 'shiftwidth', 4) print(vim.api.nvim_win_get_option(0, 'number')) -- true print(vim.api.nvim_buf_get_option(10, 'shiftwidth')) -- 4 < Using meta-accessors~ A few meta-accessors are available if you want to set options in a more "idiomatic" way. They essentially wrap the above API functions and allow you to manipulate options as if they were variables: - |vim.o|: behaves like `:let &{option-name}` - |vim.go|: behaves like `:let &g:{option-name}` - |vim.bo|: behaves like `:let &l:{option-name}` for buffer-local options - |vim.wo|: behaves like `:let &l:{option-name}` for window-local options > vim.o.smarttab = false -- let &smarttab = v:false print(vim.o.smarttab) -- false vim.o.isfname = vim.o.isfname .. ',@-@' -- on Linux: let &isfname = &isfname .. ',@-@' print(vim.o.isfname) -- '@,48-57,/,.,-,_,+,,,#,$,%,~,=,@-@' vim.bo.shiftwidth = 4 print(vim.bo.shiftwidth) -- 4 < You can specify a number for buffer-local and window-local options. If no number is given, the current buffer/window is used: > vim.bo[4].expandtab = true -- same as vim.api.nvim_buf_set_option(4, 'expandtab', true) vim.wo.number = true -- same as vim.api.nvim_win_set_option(0, 'number', true) < These wrappers also have more sophisticated `vim.opt*` variants that provide convenient mechanisms for setting options in Lua. They're similar to what you might be used to in your `init.vim`: - `vim.opt`: behaves like `:set` - `vim.opt_global`: behaves like `:setglobal` - `vim.opt_local`: behaves like `:setlocal` > vim.opt.smarttab = false print(vim.opt.smarttab:get()) -- false < Some options can be set using Lua tables: > vim.opt.completeopt = {'menuone', 'noselect'} print(vim.inspect(vim.opt.completeopt:get())) -- { "menuone", "noselect" } < Wrappers for list-like, map-like and set-like options also come with methods and metamethods that work similarly to their `:set+=`, `:set^=` and `:set-=` counterparts in Vimscript. > vim.opt.shortmess:append({ I = true }) -- alternative form: vim.opt.shortmess = vim.opt.shortmess + { I = true } vim.opt.whichwrap:remove({ 'b', 's' }) -- alternative form: vim.opt.whichwrap = vim.opt.whichwrap - { 'b', 's' } < Be sure to look at |vim.opt| for more information. See also: - |lua-vim-options| ============================================================================== MANAGING VIM INTERNAL VARIABLES *luaguide-managing-vim-internal-variables* Using api functions~ Much like options, internal variables have their own set of API functions: - Global variables (`g:`): - |nvim_set_var()| - |nvim_get_var()| - |nvim_del_var()| - Buffer variables (`b:`): - |nvim_buf_set_var()| - |nvim_buf_get_var()| - |nvim_buf_del_var()| - Window variables (`w:`): - |nvim_win_set_var()| - |nvim_win_get_var()| - |nvim_win_del_var()| - Tabpage variables (`t:`): - |nvim_tabpage_set_var()| - |nvim_tabpage_get_var()| - |nvim_tabpage_del_var()| - Predefined Vim variables (`v:`): - |nvim_set_vvar()| - |nvim_get_vvar()| With the exception of predefined Vim variables, they can also be deleted (the `:unlet` command is the equivalent in Vimscript). Local variables (`l:`), script variables (`s:`) and function arguments (`a:`) cannot be manipulated as they only make sense in the context of a Vim script, Lua has its own scoping rules. If you are unfamiliar with what these variables do, |internal-variables| describes them in detail. These functions take a string containing the name of the variable to set/get/delete as well as the value you want to set it to. > vim.api.nvim_set_var('some_global_variable', { key1 = 'value', key2 = 300 }) print(vim.inspect(vim.api.nvim_get_var('some_global_variable'))) -- { key1 = "value", key2 = 300 } vim.api.nvim_del_var('some_global_variable') < Variables that are scoped to a buffer, a window or a tabpage also receive a number (using `0` will set/get/delete the variable for the current buffer/window/tabpage): > vim.api.nvim_win_set_var(0, 'some_window_variable', 2500) vim.api.nvim_tab_set_var(3, 'some_tabpage_variable', 'hello world') print(vim.api.nvim_win_get_var(0, 'some_window_variable')) -- 2500 print(vim.api.nvim_buf_get_var(3, 'some_tabpage_variable')) -- 'hello world' vim.api.nvim_win_del_var(0, 'some_window_variable') vim.api.nvim_buf_del_var(3, 'some_tabpage_variable') < Using meta-accessors~ Internal variables can be manipulated more intuitively using these meta-accessors: - |vim.g|: global variables - |vim.b|: buffer variables - |vim.w|: window variables - |vim.t|: tabpage variables - |vim.v|: predefined Vim variables - |vim.env|: environment variables > vim.g.some_global_variable = { key1 = 'value', key2 = 300 } print(vim.inspect(vim.g.some_global_variable)) -- { key1 = "value", key2 = 300 } -- target a specific buffer/window/tabpage (Neovim 0.6+) vim.b[2].myvar = 1 < Some variable names may contain characters that cannot be used for identifiers in Lua. You can still manipulate these variables by using this syntax: `vim.g['my#variable']`. To delete one of these variables, simply assign `nil` to it: > vim.g.some_global_variable = nil < See also: - |lua-vim-variables| Caveats~ You cannot add/update/delete keys from a dictionary stored in one of these variables. For example, this snippet of Vimscript code does not work as expected: > let g:variable = {} lua vim.g.variable.key = 'a' echo g:variable " {} < You can use a temporary variable as a workaround: > let g:variable = {} lua << EOF local tmp = vim.g.variable tmp.key = 'a' vim.g.variable = tmp EOF echo g:variable " {'key': 'a'} < This is a known issue: - Issue #12544: https://github.com/neovim/neovim/issues/12544 ============================================================================== CALLING VIMSCRIPT FUNCTIONS *luaguide-calling-vimscript-functions* vim.fn.{function}()~ `vim.fn` can be used to call a Vimscript function. Data types are converted back and forth from Lua to Vimscript. > print(vim.fn.printf('Hello from %s', 'Lua')) local reversed_list = vim.fn.reverse({ 'a', 'b', 'c' }) print(vim.inspect(reversed_list)) -- { "c", "b", "a" } local function print_stdout(chan_id, data, name) print(data[1]) end vim.fn.jobstart('ls', { on_stdout = print_stdout }) < Hashes (`#`) are not valid characters for identifiers in Lua, so autoload functions have to be called with this syntax: > vim.fn['my#autoload#function']() < The functionality of `vim.fn` is identical to `vim.call`, but allows a more Lua-like syntax. It is distinct from `vim.api.nvim_call_function` in that converting Vim/Lua objects is automatic: `vim.api.nvim_call_function` returns a table for floating point numbers and does not accept Lua closures while `vim.fn` handles these types transparently. See also: - |vim.fn| Tips~ Neovim has an extensive library of powerful built-in functions that are very useful for plugins. See |vim-function| for an alphabetical list and |function-list| for a list of functions grouped by topic. Neovim API functions can be used directly through `vim.api.{..}`. See |api| for information. Caveats~ Some Vim functions that should return a boolean return `1` or `0` instead. This isn't a problem in Vimscript as `1` is truthy and `0` falsy, enabling constructs like these: > if has('nvim') " do something... endif < In Lua however, only `false` and `nil` are considered falsy, numbers always evaluate to `true` no matter their value. You have to explicitly check for `1` or `0`: > if vim.fn.has('nvim') == 1 then -- do something... end < ============================================================================== DEFINING MAPPINGS *luaguide-defining-mappings* API functions~ Neovim provides a list of API functions to set, get and delete mappings: - Global mappings: - |nvim_set_keymap()| - |nvim_get_keymap()| - |nvim_del_keymap()| - Buffer-local mappings: - |nvim_buf_set_keymap()| - |nvim_buf_get_keymap()| - |nvim_buf_del_keymap()| Let's start with `vim.api.nvim_set_keymap()` and `vim.api.nvim_buf_set_keymap()` The first argument passed to the function is a string containing the name of the mode for which the mapping will take effect: | String value | Help page | Affected modes | Vimscript equivalent | | ---------------------- | ------------- | ---------------------------------------- | -------------------- | | `''` (an empty string) | `mapmode-nvo` | Normal, Visual, Select, Operator-pending | `:map` | | `'n'` | `mapmode-n` | Normal | `:nmap` | | `'v'` | `mapmode-v` | Visual and Select | `:vmap` | | `'s'` | `mapmode-s` | Select | `:smap` | | `'x'` | `mapmode-x` | Visual | `:xmap` | | `'o'` | `mapmode-o` | Operator-pending | `:omap` | | `'!'` | `mapmode-ic` | Insert and Command-line | `:map!` | | `'i'` | `mapmode-i` | Insert | `:imap` | | `'l'` | `mapmode-l` | Insert, Command-line, Lang-Arg | `:lmap` | | `'c'` | `mapmode-c` | Command-line | `:cmap` | | `'t'` | `mapmode-t` | Terminal | `:tmap` | The second argument is a string containing the left-hand side of the mapping (the key or set of keys that trigger the command defined in the mapping). An empty string is equivalent to ``, which disables a key. The third argument is a string containing the right-hand side of the mapping (the command to execute). The final argument is a table containing boolean options for the mapping as defined in |:map-arguments|. Since Neovim 0.7.0, you can also pass a `callback` option to invoke a Lua function instead of the right-hand side when executing the mapping. Buffer-local mappings also take a buffer number as their first argument (`0` sets the mapping for the current buffer). > vim.api.nvim_set_keymap('n', '', ':set hlsearch!', { noremap = true, silent = true }) -- :nnoremap :set hlsearch vim.api.nvim_set_keymap('n', 'tegf', [[lua require('telescope.builtin').git_files()]], { noremap = true, silent = true }) -- :nnoremap tegf lua require('telescope.builtin').git_files() vim.api.nvim_buf_set_keymap(0, '', 'cc', 'line(".") == 1 ? "cc" : "ggcc"', { noremap = true, expr = true }) -- :noremap cc line('.') == 1 ? 'cc' : 'ggcc' vim.api.nvim_set_keymap('n', 'ex', '', { noremap = true, callback = function() print('My example') end, -- Since Lua function don't have a useful string representation, you can use the "desc" option to document your mapping desc = 'Prints "My example" in the message area', }) < `vim.api.nvim_get_keymap()` takes a string containing the shortname of the mode for which you want the list of mappings (see table above). The return value is a table containing all global mappings for the mode. > print(vim.inspect(vim.api.nvim_get_keymap('n'))) -- :verbose nmap < `vim.api.nvim_buf_get_keymap()` takes an additional buffer number as its first argument (`0` will get mapppings for the current bufffer) > print(vim.inspect(vim.api.nvim_buf_get_keymap(0, 'i'))) -- :verbose imap < `vim.api.nvim_del_keymap()` takes a mode and the left-hand side of a mapping. > vim.api.nvim_del_keymap('n', '') -- :nunmap < Again, `vim.api.nvim_buf_del_keymap()`, takes a buffer number as its first argument, with `0` representing the current buffer. > vim.api.nvim_buf_del_keymap(0, 'i', '') -- :iunmap < vim.keymap~ WARNING: The functions discussed in this section are only available in Neovim 0.7.0+ Neovim provides two functions to set/del mappings: - |vim.keymap.set()| - |vim.keymap.del()| These are similar to the above API functions with added syntactic sugar. `vim.keymap.set()` takes a string as its first argument. It can also be a table of strings to define mappings for multiple modes at once: > vim.keymap.set('n', 'ex1', 'lua vim.notify("Example 1")') vim.keymap.set({'n', 'c'}, 'ex2', 'lua vim.notify("Example 2")') < The second argument is the left-hand side of the mapping. The third argument is the right-hand side of the mapping, which can either be a string or a Lua function: > vim.keymap.set('n', 'ex1', 'echomsg "Example 1"') vim.keymap.set('n', 'ex2', function() print("Example 2") end) vim.keymap.set('n', 'pl1', require('plugin').plugin_action) -- To avoid the startup cost of requiring the module, you can wrap it in a function to require it lazily when invoking the mapping: vim.keymap.set('n', 'pl2', function() require('plugin').plugin_action() end) < The fourth (optional) argument is a table of options that correspond to the options passed to `vim.api.nvim_set_keymap()`, with a few additions (see |vim.keymap.set()|. > vim.keymap.set('n', 'ex1', 'echomsg "Example 1"', {buffer = true}) vim.keymap.set('n', 'ex2', function() print('Example 2') end, {desc = 'Prints "Example 2" to the message area'}) < Defining keymaps with a Lua function is different from using a string. The usual way to show information about a keymap like `:nmap ex1` will not output useful information (the string itself), but instead only show `Lua function`. It is recommended to add a `desc` key to describe the behavior of your keymap. This is especially important for documenting plugin mappings so users can understand the usage of the keymap more easily. An interesting feature of this API is that it irons out some historical quirks of Vim mappings: - Mappings are `noremap` by default, except when the `rhs` is a `` mapping. This means you rarely have to think about whether a mapping should be recursive or not: ```lua vim.keymap.set('n', 'test1', 'echo "test"') -- :nnoremap test echo "test" -- If you DO want the mapping to be recursive, set the "remap" option to "true" vim.keymap.set('n', '>', ']', {remap = true}) -- :nmap > ] -- mappings don't work unless they're recursive, vim.keymap.set() handles that for you automatically vim.keymap.set('n', 'plug', '(plugin)') -- :nmap plug (plugin) ``` - In `expr` mappings, `nvim_replace_termcodes()` is automatically applied to strings returned from Lua functions: ```lua vim.keymap.set('i', '', function() return vim.fn.pumvisible == 1 and '' or '' end, {expr = true}) ``` See also: - |recursive_mapping| `vim.keymap.del()` works the same way but deletes mappings instead: > vim.keymap.del('n', 'ex1') vim.keymap.del({'n', 'c'}, 'ex2', {buffer = true}) < ============================================================================== DEFINING USER COMMANDS *luaguide-defining-user-commands* WARNING: The API functions discussed in this section are only available in Neovim 0.7.0+ Neovim provides API functions for user-defined commands: - Global user commands: - |nvim_create_user_command()| - |nvim_del_user_command()| - Buffer-local user commands: - |nvim_buf_create_user_command()| - |nvim_buf_del_user_command()| Let's start with `vim.api.nvim_create_user_command()` The first argument passed to this function is the name of the command (which must start with an uppercase letter). The second argument is the code to execute when invoking said command. It can either be: A string (in which case it will be executed as Vimscript). You can use escape sequences like ``, ``, etc. like you would with `:command` > vim.api.nvim_create_user_command('Upper', 'echo toupper()', { nargs = 1 }) -- :command! -nargs=1 Upper echo toupper() vim.cmd('Upper hello world') -- prints "HELLO WORLD" < Or a Lua function. It receives a dictionary-like table that contains the data normally provided by escape sequences (see |nvim_create_user_command()| > vim.api.nvim_create_user_command( 'Upper', function(opts) print(string.upper(opts.args)) end, { nargs = 1 } ) < The third argument lets you pass command attributes as a table (see |command-attributes|`. Since you can already define buffer-local user commands with |nvim_buf_create_user_command()|, `-buffer` is not a valid attribute. Two additional attributes are available: - `desc` allows you to control what gets displayed when you run `:command {cmd}` on a command defined as a Lua callback. Similarly to keymaps, it is recommended to add a `desc` key to commands defined as Lua functions. - `force` is equivalent to calling `:command!` and replaces a command if one with the same name already exists. It is true by default, unlike its Vimscript equivalent. The `-complete` attribute can take a Lua function in addition to the attributes listed in |:command-complete|. > vim.api.nvim_create_user_command('Upper', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) -- return completion candidates as a list-like table return { 'foo', 'bar', 'baz' } end, }) < Buffer-local user commands also take a buffer number as their first argument. This is an advantage over `-buffer` which can only define a command for the current buffer. > vim.api.nvim_buf_create_user_command(4, 'Upper', function() end, {}) < `vim.api.nvim_del_user_command()` takes a command name. > vim.api.nvim_del_user_command('Upper') -- :delcommand Upper < Again, `vim.api.nvim_buf_del_user_command()`, takes a buffer number as its first argument, with `0` representing the current buffer. > vim.api.nvim_buf_del_user_command(4, 'Upper') < See also: - |nvim_create_user_command()| - |40.2| - |command-attributes| Caveats~ The `-complete=custom` attribute automatically filters completion candidates and has built-in wildcard (|wildcard| support: > function! s:completion_function(ArgLead, CmdLine, CursorPos) abort return join([ \ 'strawberry', \ 'star', \ 'stellar', \ ], "\n") endfunction command! -nargs=1 -complete=custom,s:completion_function Test echo " Typing `:Test st[ae]` returns "star" and "stellar" < Passing a Lua function to `complete` makes it behave like `customlist` which leaves filtering up to the user: > vim.api.nvim_create_user_command('Test', function() end, { nargs = 1, complete = function(ArgLead, CmdLine, CursorPos) return { 'strawberry', 'star', 'stellar', } end, }) -- Typing `:Test z` returns all the completion results because the list was not filtered < ============================================================================== DEFINING AUTOCOMMANDS *luaguide-defining-autocommands* (this section is a work in progress) Neovim 0.7.0 has API functions for autocommands. See `:help api-autocmd` for details - Pull request #14661: https://github.com/neovim/neovim/pull/14661 lua: autocmds take 2 ============================================================================== DEFINING HIGHLIGHTS *luaguide-defining-highlights* (this section is a work in progress) Neovim 0.7.0 has API functions for highlight groups. See also: - |nvim_set_hl()| - |nvim_get_hl_by_id()| - |nvim_get_hl_by_name()| ============================================================================== GENERAL TIPS AND RECOMMENDATIONS *luaguide-general-tips-and-recommendations* Reloading cached modules~ In Lua, the `require()` function caches modules. This is a good thing for performance, but it can make working on plugins a bit cumbersome because modules are not updated on subsequent `require()` calls. If you'd like to refresh the cache for a particular module, you have to modify the `package.loaded` global table: > package.loaded['modname'] = nil require('modname') -- loads an updated version of module 'modname' < The nvim-lua/plenary.nvim: https://github.com/nvim-lua/plenary.nvim plugin has a custom function: https://github.com/nvim-lua/plenary.nvim/blob/master/lua/plenary/reload.lua that does this for you. Don't pad Lua strings!~ When using double bracketed strings, resist the temptation to pad them! While it is fine to do in contexts where spaces are ignored, it can cause hard to debug issues when whitespace is significant: > vim.api.nvim_set_keymap('n', 'f', [[ call foo() ]], {noremap = true}) < In the above example, `f` is mapped to `call foo()` instead of `call foo()`. Notes about Vimscript <-> Lua type conversion~ Converting a variable creates a copy:~ You can't directly interact with the reference to a Vim object from Lua or a Lua object from Vimscript. For example, the `map()` function in Vimscript modifies a variable in place: > let s:list = [1, 2, 3] let s:newlist = map(s:list, {_, v -> v * 2}) echo s:list " [2, 4, 6] echo s:newlist " [2, 4, 6] echo s:list is# s:newlist " 1 < Using this function from Lua creates a copy instead: > local tbl = {1, 2, 3} local newtbl = vim.fn.map(tbl, function(_, v) return v * 2 end) print(vim.inspect(tbl)) -- { 1, 2, 3 } print(vim.inspect(newtbl)) -- { 2, 4, 6 } print(tbl == newtbl) -- false < Conversion is not always possible~ This mostly affects functions and tables: Lua tables that are a mix between a List and a Dictionary can't be converted: > print(vim.fn.count({1, 1, number = 1}, 1)) -- E5100: Cannot convert given lua table: table should either have a sequence of positive integer keys or contain only string keys < While you can call Vim functions in Lua with `vim.fn`, you can't hold references to them. This can cause surprising behaviors: > local FugitiveHead = vim.fn.funcref('FugitiveHead') print(FugitiveHead) -- vim.NIL vim.cmd("let g:test_dict = {'test_lambda': {-> 1}}") print(vim.g.test_dict.test_lambda) -- nil print(vim.inspect(vim.g.test_dict)) -- {} < Passing Lua functions to Vim functions is OK, storing them in Vim variables is not (fixed in Neovim 0.7.0+): > -- This works: vim.fn.jobstart({'ls'}, { on_stdout = function(chan_id, data, name) print(vim.inspect(data)) end }) -- This doesn't: vim.g.test_dict = {test_lambda = function() return 1 end} -- Error: Cannot convert given lua type < Note however that doing the same from Vimscript with `luaeval()` **does** work: > let g:test_dict = {'test_lambda': luaeval('function() return 1 end')} echo g:test_dict " {'test_lambda': function('4714')} < Vim booleans~ A common pattern in Vim scripts is to use `1` or `0` instead of proper booleans. Indeed, Vim did not have a separate boolean type until version 7.4.1154. Lua booleans are converted to actual booleans in Vimscript, not numbers: > lua vim.g.lua_true = true echo g:lua_true " v:true lua vim.g.lua_false = false echo g:lua_false " v:false < Setting up linters/language servers~ If you're using linters and/or language servers to get diagnostics and autocompletion for Lua projects, you may have to configure Neovim-specific settings for them. Here are a few recommended settings for popular tools: luacheck~ You can get luacheck: https://github.com/mpeterv/luacheck/ to recognize the `vim` global by putting this configuration in `~/.luacheckrc` or `$XDG_CONFIG_HOME/luacheck/.luacheckrc` : > globals = { "vim", } < The Alloyed/lua-lsp: https://github.com/Alloyed/lua-lsp/ language server uses `luacheck` to provide linting and reads the same file. For more information on how to configure `luacheck`, please refer to its documentation: https://luacheck.readthedocs.io/en/stable/config.html sumneko/lua-language-server~ The nvim-lspconfig: https://github.com/neovim/nvim-lspconfig/ repository contains instructions to configure sumneko/lua-language-server: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#sumneko_lua the example uses the built-in LSP client but the configuration should be identical for other LSP client implementations . For more information on how to configure sumneko/lua-language-server: https://github.com/sumneko/lua-language-server/ see "Setting": https://github.com/sumneko/lua-language-server/wiki/Setting coc.nvim~ The rafcamlet/coc-nvim-lua: https://github.com/rafcamlet/coc-nvim-lua/ completion source for coc.nvim: https://github.com/neoclide/coc.nvim/ provides completion items for the Neovim stdlib. Debugging Lua code~ You can debug Lua code running in a separate Neovim instance with jbyuki/one-small-step-for-vimkind: https://github.com/jbyuki/one-small-step-for-vimkind The plugin uses the Debug Adapter Protocol: https://microsoft.github.io/debug-adapter-protocol/ . Connecting to a debug adapter requires a DAP client like mfussenegger/nvim-dap: https://github.com/mfussenegger/nvim-dap/ or puremourning/vimspector: https://github.com/puremourning/vimspector/ . Debugging Lua mappings/commands/autocommands~ The `:verbose` command allows you to see where a mapping/command/autocommand was defined: > :verbose map m < > n m_ * echo 'example' Last set from ~/.config/nvim/init.vim line 26 < By default, this feature is disabled in Lua for performance reasons. You can enable it by starting Neovim with a verbose level greater than 0: > nvim -V1 < See also: - |'verbose'| - |-V| - neovim/neovim#15079: https://github.com/neovim/neovim/pull/15079 Testing Lua code~ - plenary.nvim: test harness: https://github.com/nvim-lua/plenary.nvim/#plenarytest_harness - notomo/vusted: https://github.com/notomo/vusted Using Luarocks packages~ wbthomason/packer.nvim: https://github.com/wbthomason/packer.nvim supports Luarocks packages. Instructions for how to set this up are available in the README: https://github.com/wbthomason/packer.nvim/#luarocks-support ============================================================================== MISCELLANEOUS *luaguide-miscellaneous* vim.loop~ `vim.loop` is the module that exposes the LibUV API. Some resources: - Official documentation for LibUV: https://docs.libuv.org/en/v1.x/ - Luv documentation: https://github.com/luvit/luv/blob/master/docs.md - teukka.tech - Using LibUV in Neovim: https://teukka.tech/posts/2020-01-07-vimloop/ See also: - |vim.loop| vim.lsp~ `vim.lsp` is the module that controls the built-in LSP client. The neovim/nvim-lspconfig: https://github.com/neovim/nvim-lspconfig/ repository contains default configurations for popular language servers. The behavior of the client can be configured using "lsp-handlers". For more information: - |lsp-handler| - neovim/neovim#12655: https://github.com/neovim/neovim/pull/12655 - How to migrate from diagnostic-nvim: https://github.com/nvim-lua/diagnostic-nvim/issues/73#issue-737897078 You may also want to take a look at plugins built around the LSP client: https://github.com/rockerBOO/awesome-neovim#lsp See also: - |lsp| vim.treesitter~ `vim.treesitter` is the module that controls the integration of the Tree-sitter: https://tree-sitter.github.io/tree-sitter/ library in Neovim. If you want to know more about Tree-sitter, you may be interested in this presentation 38:37 : https://www.youtube.com/watch?v=Jes3bD6P0To . The nvim-treesitter: https://github.com/nvim-treesitter/ organisation hosts various plugins taking advantage of the library. See also: - |lua-treesitter| Transpilers~ One advantage of using Lua is that you don't actually have to write Lua code! There is a multitude of transpilers available for the language. - Moonscript: https://moonscript.org/ Probably one of the most well-known transpilers for Lua. Adds a lots of convenient features like classes, list comprehensions or function literals. The svermeulen/nvim-moonmaker: https://github.com/svermeulen/nvim-moonmaker plugin allows you to write Neovim plugins and configuration directly in Moonscript. - Fennel: https://fennel-lang.org/ A lisp that compiles to Lua. You can write configuration and plugins for Neovim in Fennel with the Olical/aniseed: https://github.com/Olical/aniseed or the Hotpot: https://github.com/rktjmp/hotpot.nvim plugin. Additionally, the Olical/conjure: https://github.com/Olical/conjure plugin provides an interactive development environment that supports Fennel among other languages . - Teal: https://github.com/teal-language/tl The name Teal comes from pronouncing TL typed lua . This is exactly what it tries to do - add strong typing to lua while otherwise remaining close to standard lua syntax. The nvim-teal-maker: https://github.com/svermeulen/nvim-teal-maker plugin can be used to write Neovim plugins or configuration files directly in Teal Other interesting projects: - TypeScriptToLua/TypeScriptToLua: https://github.com/TypeScriptToLua/TypeScriptToLua - Haxe: https://haxe.org/ - SwadicalRag/wasm2lua: https://github.com/SwadicalRag/wasm2lua - hengestone/lua-languages: https://github.com/hengestone/lua-languages vim:tw=78:ts=8:noet:ft=help:norl: ================================================ FILE: scripts/docgen.sh ================================================ #!/usr/bin/env sh ./to_vimdoc.sed ../README.md | fmt -s | ./sections_tags.awk > ../doc/nvim-lua-guide.txt ./to_vimdocja.sed ../README.ja.md | fmt -s | ./sections_tags.awk > ../doc/nvim-lua-guide.jax ================================================ FILE: scripts/sections_tags.awk ================================================ #!/usr/bin/awk -f { if (lastline ~ /^=+$/) { tag = tolower($0) gsub(/[^A-Za-z]/, "-", tag) print $0 printf("%80s", "*" "luaguide-" tag "*") print "" } else { print } } { lastline = $0 } ================================================ FILE: scripts/to_vimdoc.sed ================================================ #!/bin/sed -f # Title /^# / { s/# /*nvim-lua-guide.txt* / } # Sections /^## / { s/[a-z]/\u&/g s/## // i============================================================================== } # Sub-sections, tips and caveats /^####\? / { s/####\? // s/.*/&~/ } # Help links s/\[`vim\.api\.\(.*\)`\](.*)/|\1|/ s/\[`:help \(.*\)`\](.*)/|\1|/ s/\[`\(.*\)`\](.*)/|\1|/ # Markdown links /\[.*\](http.*)/ { y/[]()/ : / } # Todos s/\*\*TODO\*\*: /\t*Todo\t/g # Warnings s/\*\*\(WARNING\)\*\*/\1/ # Code blocks /^```.*$/,/^```$/{ s/.*/ &/ s/```.\+/>/ s/\s*```$// s/\s*```$/