run docgen.sh

doc/nvim-lua-guide.txt

@@ -438,7 +438,7 @@ types and vice versa.
     EOF
 
     inoremap <silent> <expr> <Tab>
-        \ pumvisible() ? "\<C-n>" :
+        \ pumvisible() ? "\<C-N>" :
         \ v:lua.check_back_space() ? "\<Tab>" :
         \ 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 <expr> <Tab> pumvisible() ? "\<C-n>" : "\<Tab>"
+    inoremap <expr> <Tab> pumvisible() ? "\<C-N>" : "\<Tab>"
 <
 
 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 [[\<C-n>]] or [[\<Tab>]]
+        return vim.fn.pumvisible() == 1 and [[\<C-N>]] or [[\<Tab>]]
     end
 
     vim.api.nvim_set_keymap('i', '<Tab>', 'v:lua.smart_tab()', {expr =
     true, noremap = true})
 <
 
-only to find out that the mapping inserts `\<Tab>` and `\<C-n>`
+only to find out that the mapping inserts `\<Tab>` and `\<C-N>`
 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'<C-n>' or t'<Tab>'
+        return vim.fn.pumvisible() == 1 and t'<C-N>' or t'<Tab>'
     end
 
     vim.api.nvim_set_keymap('i', '<Tab>', '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', '<Tab>', function()
+        return vim.fn.pumvisible() == 1 and '<C-N>' or '<Tab>'
+    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 <buffer> <expr> cc line('.') == 1 ? 'cc' : 'ggcc'
+
+    vim.api.nvim_set_keymap('n', '<Leader>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 <buffer> <Tab>
 <
 
+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', '<Leader>ex1', '<Cmd>lua vim.notify("Example
+    1")<CR>')
+    vim.keymap.set({'n', 'c'}, '<Leader>ex2', '<Cmd>lua
+    vim.notify("Example 2")<CR>')
+<
+
+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', '<Leader>ex1', '<Cmd>echomsg "Example 1"<CR>')
+    vim.keymap.set('n', '<Leader>ex2', function() print("Example 2") end)
+    vim.keymap.set('n', '<Leader>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', '<Leader>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', '<Leader>ex1', '<Cmd>echomsg "Example 1"<CR>',
+    {buffer = true})
+    vim.keymap.set('n', '<Leader>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 `<Plug>`
+mapping. This means you rarely have to think about whether a mapping
+should be recursive or not:
+    ```lua
+    vim.keymap.set('n', '<Leader>test1', '<Cmd>echo "test"<CR>')
+    -- :nnoremap <Leader>test <Cmd>echo "test"<CR>
+
+    -- If you DO want the mapping to be recursive, set the "remap"
+    option to "true"
+    vim.keymap.set('n', '>', ']', {remap = true})
+    -- :nmap > ]
+
+    -- <Plug> mappings don't work unless they're recursive,
+    vim.keymap.set() handles that for you automatically
+    vim.keymap.set('n', '<Leader>plug', '<Plug>(plugin)')
+    -- :nmap <Leader>plug <Plug>(plugin)
+    ```
+- In `expr` mappings, `nvim_replace_termcodes()` is automatically applied
+to strings returned from Lua functions:
+    ```lua
+    vim.keymap.set('i', '<Tab>', function()
+        return vim.fn.pumvisible == 1 and '<C-N>' or '<Tab>'
+    end, {expr = true})
+    ```
+
+See also:
+- |recursive_mapping|
+
+`vim.keymap.del()` works the same way but deletes mappings instead:
+
+    >
+    vim.keymap.del('n', '<Leader>ex1')
+    vim.keymap.del({'n', 'c'}, '<Leader>ex2', {buffer = true})
+<
+
 ==============================================================================
 DEFINING USER COMMANDS
                                                *luaguide-defining-user-commands*