Home Explore Blog CI



neovim

7th chunk of `runtime/doc/lua-guide.txt`
cc6587ba92fdb5d7f1f58722148769ff414033900f0d23cb0000000100000fba
 true`: >lua
    vim.keymap.set('n', '<Leader>ex1', '<cmd>echo "Example 1"<cr>')
    -- add a shorter mapping
    vim.keymap.set('n', 'e', '<Leader>ex1', { remap = true })
<
  Note: |<Plug>| mappings are always expanded even with the default `remap = false`: >lua
    vim.keymap.set('n', '[%', '<Plug>(MatchitNormalMultiBackward)')
<
------------------------------------------------------------------------------
Removing mappings                                       *lua-guide-mappings-del*

A specific mapping can be removed with |vim.keymap.del()|:
>lua
    vim.keymap.del('n', '<Leader>ex1')
    vim.keymap.del({'n', 'c'}, '<Leader>ex2', {buffer = true})
<
------------------------------------------------------------------------------
See also:
• `vim.api.`|nvim_get_keymap()|:     return all global mapping
• `vim.api.`|nvim_buf_get_keymap()|: return all mappings for buffer

==============================================================================
Autocommands                                            *lua-guide-autocommands*

An |autocommand| is a Vim command or a Lua function that is automatically
executed whenever one or more |events| are triggered, e.g., when a file is
read or written, or when a window is created. These are accessible from Lua
through the Nvim API.

------------------------------------------------------------------------------
Creating autocommands                             *lua-guide-autocommand-create*

Autocommands are created using `vim.api.`|nvim_create_autocmd()|, which takes
two mandatory arguments:
• {event}: a string or table of strings containing the event(s) which should
           trigger the command or function.
• {opts}:  a table with keys that control what should happen when the event(s)
           are triggered.

The most important options are:

• `pattern`:  A string or table of strings containing the |autocmd-pattern|.
            Note: Environment variable like `$HOME` and `~` are not automatically
            expanded; you need to explicitly use `vim.fn.`|expand()| for this.
• `command`:  A string containing a Vim command.
• `callback`: A Lua function.

You must specify one and only one of `command` and `callback`. If `pattern` is
omitted, it defaults to `pattern = '*'`.
Examples:
>lua
    vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
      pattern = {"*.c", "*.h"},
      command = "echo 'Entering a C or C++ file'",
    })

    -- Same autocommand written with a Lua function instead
    vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
      pattern = {"*.c", "*.h"},
      callback = function() print("Entering a C or C++ file") end,
    })

    -- User event triggered by MyPlugin
    vim.api.nvim_create_autocmd("User", {
      pattern = "MyPlugin",
      callback = function() print("My Plugin Works!") end,
    })
<
Nvim will always call a Lua function with a single table containing information
about the triggered autocommand. The most useful keys are
• `match`: a string that matched the `pattern` (see |<amatch>|)
• `buf`:   the number of the buffer the event was triggered in (see |<abuf>|)
• `file`:  the file name of the buffer the event was triggered in (see |<afile>|)
• `data`:  a table with other relevant data that is passed for some events

For example, this allows you to set buffer-local mappings for some filetypes:
>lua
    vim.api.nvim_create_autocmd("FileType", {
      pattern = "lua",
      callback = function(args)
        vim.keymap.set('n', 'K', vim.lsp.buf.hover, { buffer = args.buf })
      end
    })
<
This means that if your callback itself takes an (even optional) argument, you
must wrap it in `function() end` to avoid an error:
>lua
    vim.api.nvim_create_autocmd('TextYankPost', {
      callback = function() vim.hl.on_yank() end
    })
<
(Since unused arguments can be omitted in Lua function definitions, this is
equivalent to `function(args) ... end`.)

Instead of using a pattern, you can create a buffer-local autocommand (see
|autocmd-buflocal|)

Title: Lua: Autocommands - Creation and Usage
Summary
This section introduces autocommands in Neovim, explaining that they are automatically executed commands or Lua functions triggered by specific events. It details how to create autocommands using `vim.api.nvim_create_autocmd()`, including the required `event` and `opts` arguments. The `opts` table can contain keys like `pattern`, `command`, and `callback`, with a choice between `command` (a Vim command string) and `callback` (a Lua function). The section provides examples of creating autocommands using both Vim commands and Lua functions, including examples for setting buffer-local mappings and handling user events.