diff options
Diffstat (limited to 'runtime/doc/api.txt')
| -rw-r--r-- | runtime/doc/api.txt | 97 |
1 files changed, 31 insertions, 66 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index decd3ca7d3..6659e9b79b 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3228,89 +3228,54 @@ nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* |autocmd-groups| nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Create an |autocommand| - - The API allows for two (mutually exclusive) types of actions to be - executed when the autocommand triggers: a callback function (Lua or - Vimscript), or a command (like regular autocommands). - - Example using callback: >lua - -- Lua function - local myluafun = function() print("This buffer enters") end - - -- Vimscript function name (as a string) - local myvimfun = "g:MyVimFunction" + Creates an |autocommand| event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). + Example using Lua callback: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {"*.c", "*.h"}, - callback = myluafun, -- Or myvimfun + callback = function(ev) + print(string.format('event fired: s', vim.inspect(ev))) + end }) < - 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 - -- 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: >lua + Example using an Ex command as the handler: >lua vim.api.nvim_create_autocmd({"BufEnter", "BufWinEnter"}, { pattern = {"*.c", "*.h"}, command = "echo 'Entering a C or C++ file'", }) < - Example values for pattern: >lua - pattern = "*.py" - pattern = { "*.py", "*.pyi" } -< - - Note: The `pattern` is passed to callbacks and commands as a literal string; environment - variables like `$HOME` and `~` are not automatically expanded as they are by |:autocmd|. Instead, - |expand()| such variables explicitly: >lua + Note: `pattern` is NOT automatically expanded (unlike with |:autocmd|), thus names like + "$HOME" and "~" must be expanded explicitly: >lua pattern = vim.fn.expand("~") .. "/some/path/*.py" < - Example values for event: >lua - event = "BufWritePre" - event = {"CursorHold", "BufWritePre", "BufWritePost"} -< - Parameters: ~ - • {event} (string|array) The event or events to register this - autocommand - • {opts} Dictionary of autocommand options: - • group (string|integer) optional: the autocommand group name - or id to match against. - • pattern (string|array) optional: pattern or patterns to - match literally against |autocmd-pattern|. - • buffer (integer) optional: buffer number for buffer local + • {event} (string|array) Event(s) that will trigger the handler + (`callback` or `command`). + • {opts} Options dict: + • group (string|integer) optional: autocommand group name or + id to match against. + • pattern (string|array) optional: pattern(s) to match + literally |autocmd-pattern|. + • buffer (integer) optional: buffer number for buffer-local autocommands |autocmd-buflocal|. Cannot be used with {pattern}. - • desc (string) optional: description of the autocommand. - • callback (function|string) optional: if a string, the name - of a Vimscript function to call when this autocommand is - triggered. Otherwise, a Lua function which is called when - this autocommand is triggered. Cannot be used with - {command}. Lua callbacks can return true to delete the - autocommand; in addition, they accept a single table - argument with the following keys: - • id: (number) the autocommand id - • event: (string) the name of the event that triggered the - autocommand |autocmd-events| - • group: (number|nil) the autocommand group id, if it - exists - • match: (string) the expanded value of |<amatch>| - • buf: (number) the expanded value of |<abuf>| - • file: (string) the expanded value of |<afile>| + • desc (string) optional: description (for documentation and + troubleshooting). + • callback (function|string) optional: Lua function (or + Vimscript function name, if string) called when the + event(s) is triggered. Lua callback can return true to + delete the autocommand, and receives a table argument with + these keys: + • id: (number) autocommand id + • event: (string) name of the triggered event + |autocmd-events| + • group: (number|nil) autocommand group id, if any + • match: (string) expanded value of |<amatch>| + • buf: (number) expanded value of |<abuf>| + • file: (string) expanded value of |<afile>| • data: (any) arbitrary data passed to |nvim_exec_autocmds()| @@ -3322,7 +3287,7 @@ nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* autocommands |autocmd-nested|. Return: ~ - Integer id of the created autocommand. + Autocommand id (number) See also: ~ |autocommand| |