neovim

commit a48a0a4f7b2b1255025ceb128f6cc97fa0f992aa
parent 7e7fdca163b10f8141c72936cea82051843c83c6
Author: Mathias Fußenegger <mfussenegger@users.noreply.github.com>
Date:   Wed, 20 Apr 2022 18:42:07 +0200

docs(api): add example showing necessity to wrap callback function (#18179)

Some people ran into issues trying to use `callback = myluafun` because
of the event data payload.


Co-authored-by: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Diffstat:
M
runtime/doc/api.txt
 | 
16
++++++++++++++++
M
src/nvim/api/autocmd.c
 | 
16
++++++++++++++++

2 files changed, 32 insertions(+), 0 deletions(-)
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
@@ -3221,6 +3221,22 @@ nvim_create_autocmd({event}, {*opts})                  *nvim_create_autocmd()*
                     })
 <
 
+                Lua functions receive a table with information about the
+                autocmd event as an argument. To use a function which itself
+                accepts another (optional) parameter, wrap the function in a
+                lambda:
+>
+    -- Lua function with an optional parameter.
+    -- The autocmd callback would pass a table as argument but this
+    -- function expects number|nil
+    local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
+
+    vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+      pattern = {"*.c", "*.h"},
+      callback = function() myluafun() end,
+    })
+<
+
                 Example using command: >
                     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
                       pattern = {"*.c", "*.h"},
diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c
@@ -346,6 +346,22 @@ cleanup:
 ///     })
 /// </pre>
 ///
+/// Lua functions receive a table with information about the autocmd event as an argument. To use
+/// a function which itself accepts another (optional) parameter, wrap the function
+/// in a lambda:
+///
+/// <pre>
+///     -- Lua function with an optional parameter.
+///     -- The autocmd callback would pass a table as argument but this
+///     -- function expects number|nil
+///     local myluafun = function(bufnr) bufnr = bufnr or vim.api.nvim_get_current_buf() end
+///
+///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {
+///       pattern = {"*.c", "*.h"},
+///       callback = function() myluafun() end,
+///     })
+/// </pre>
+///
 /// Example using command:
 /// <pre>
 ///     vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, {