From 25d4602bf16d61337e72b90bac8609352c5f93f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Sterle?= Date: Fri, 22 Apr 2022 00:33:20 +0200 Subject: [PATCH] run docgen.sh --- doc/nvim-lua-guide.txt | 120 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 114 insertions(+), 6 deletions(-) diff --git a/doc/nvim-lua-guide.txt b/doc/nvim-lua-guide.txt index bd4e670..0774847 100644 --- a/doc/nvim-lua-guide.txt +++ b/doc/nvim-lua-guide.txt @@ -438,7 +438,7 @@ types and vice versa. EOF inoremap - \ pumvisible() ? "\" : + \ pumvisible() ? "\" : \ v:lua.check_back_space() ? "\" : \ completion#trigger_completion() @@ -651,7 +651,7 @@ This API function allows you to escape terminal codes and Vim keycodes. You may have come across mappings like this one: > - inoremap pumvisible() ? "\" : "\" + inoremap pumvisible() ? "\" : "\" < Trying to do the same in Lua can prove to be a challenge. You might be @@ -659,14 +659,14 @@ tempted to do it like this: > function _G.smart_tab() - return vim.fn.pumvisible() == 1 and [[\]] or [[\]] + 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 `\` +only to find out that the mapping inserts `\` and `\` literally... Being able to escape keycodes is actually a Vimscript feature. Aside @@ -704,13 +704,23 @@ Coming back to our earlier example, this should now work as expected: end function _G.smart_tab() - return vim.fn.pumvisible() == 1 and t'' or t'' + 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| @@ -1049,6 +1059,8 @@ check for `1` or `0`: DEFINING MAPPINGS *luaguide-defining-mappings* +API functions~ + Neovim provides a list of API functions to set, get and delete mappings: - Global mappings: @@ -1088,7 +1100,9 @@ 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|. +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). @@ -1106,6 +1120,16 @@ Buffer-local mappings also take a buffer number as their first argument 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 @@ -1141,6 +1165,90 @@ first argument, with `0` representing the current buffer. -- :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'}) +< + +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*