diff options
Diffstat (limited to 'runtime')
| -rw-r--r-- | runtime/doc/api.txt | 251 |
1 files changed, 164 insertions, 87 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index fa2f8f974a..13179e9d9e 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -3152,129 +3152,206 @@ nvim_tabpage_set_var({tabpage}, {name}, {value}) Autocmd Functions *api-autocmd* nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* - Create or get an augroup. + Create or get an autocommand group |autocmd-groups|. - To get an existing augroup ID, do: > - local id = vim.api.nvim_create_augroup(name, { + To get an existing group id, do: > + local id = vim.api.nvim_create_augroup("MyGroup", { clear = false }) < Parameters: ~ - {name} String: The name of the augroup to create - {opts} Parameters - • clear (bool): Whether to clear existing commands - or not. Defaults to true. See |autocmd-groups| + {name} String: The name of the group + {opts} Dictionary Parameters + • clear (bool) optional: defaults to true. Clear + existing commands if the group already exists + |autocmd-groups|. Return: ~ - opaque value to use with nvim_del_augroup_by_id + Integer id of the created group. + + See also: ~ + |autocmd-groups| nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()* - Create an autocmd. + Create an |autocommand| - Examples: - • event: "pat1,pat2,pat3", - • event: "pat1" - • event: { "pat1" } - • event: { "pat1", "pat2", "pat3" } + 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). - Parameters: ~ - {event} The event or events to register this autocmd - Required keys: event: string | ArrayOf(string) + Example using callback: > + -- Lua function + local myluafun = function() print("This buffer enters") end - Parameters: ~ - {opts} Optional Parameters: - • callback: (string|function) - • (string): The name of the viml function to - execute when triggering this autocmd - • (function): The lua function to execute when - triggering this autocmd - • NOTE: Cannot be used with {command} + -- Vimscript function name (as a string) + local myvimfun = "g:MyVimFunction" - • command: (string) command - • vimscript command - • NOTE: Cannot be used with {callback} Eg. - command = "let g:value_set = v:true" + vim.api.nvim_create_autocmd({ + event = {"BufEnter", "BufWinEnter"}, + pattern = {"*.c", "*.h"}, + callback = myluafun, -- Or myvimfun + }) +< + + Example using command: > + vim.api.nvim_create_autocmd({ + event = {"BufEnter", "BufWinEnter"}, + pattern = {"*.c", "*.h"}, + command = "echo 'Entering a C or C++ file'", + }) +< - • pattern: (string|table) - • pattern or patterns to match against - • defaults to "*". - • NOTE: Cannot be used with {buffer} + Example values for pattern: > + pattern = "*.py" + pattern = { "*.py", "*.pyi" } +< - • buffer: (bufnr) - • create a |autocmd-buflocal| autocmd. - • NOTE: Cannot be used with {pattern} + Examples values for event: > + event = "BufPreWrite" + event = {"CursorHold", "BufPreWrite", "BufPostWrite"} +< - • group: (string|int) The augroup name or id - • once: (boolean) - See |autocmd-once| - • nested: (boolean) - See |autocmd-nested| - • desc: (string) - Description of the autocmd + 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 against |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: Lua + function or Vim function (as string) to execute + on event. Cannot be used with {command} + • command (string) optional: Vim command to + execute on event. Cannot be used with + {callback} + • once (boolean) optional: defaults to false. Run + the autocommand only once |autocmd-once|. + • nested (boolean) optional: defaults to false. + Run nested autocommands |autocmd-nested|. + + Return: ~ + Integer id of the created autocommand. - Return: ~ - opaque value to use with nvim_del_autocmd + See also: ~ + |autocommand| + |nvim_del_autocmd()| nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* - Delete an augroup by {id}. {id} can only be returned when - augroup was created with |nvim_create_augroup|. + Delete an autocommand group by id. - NOTE: behavior differs from augroup-delete. + To get a group id one can use |nvim_get_autocmds()|. - When deleting an augroup, autocmds contained by this augroup - will also be deleted and cleared. This augroup will no longer - exist + NOTE: behavior differs from |augroup-delete|. When deleting a + group, autocommands contained in this group will also be + deleted and cleared. This group will no longer exist. -nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* - Delete an augroup by {name}. + Parameters: ~ + {id} Integer The id of the group. - NOTE: behavior differs from augroup-delete. + See also: ~ + |nvim_del_augroup_by_name()| + |nvim_create_augroup()| - When deleting an augroup, autocmds contained by this augroup - will also be deleted and cleared. This augroup will no longer - exist +nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* + Delete an autocommand group by name. -nvim_del_autocmd({id}) *nvim_del_autocmd()* - Delete an autocmd by {id}. Autocmds only return IDs when - created via the API. Will not error if called and no autocmds - match the {id}. + NOTE: behavior differs from |augroup-delete|. When deleting a + group, autocommands contained in this group will also be + deleted and cleared. This group will no longer exist. Parameters: ~ - {id} Integer The ID returned by nvim_create_autocmd + {name} String The name of the group. -nvim_do_autocmd({event}, {*opts}) *nvim_do_autocmd()* - Do one autocmd. + See also: ~ + |autocommand-groups| + +nvim_del_autocmd({id}) *nvim_del_autocmd()* + Delete an autocommand by id. + + NOTE: Only autocommands created via the API have an id. Parameters: ~ - {event} The event or events to execute - {opts} Optional Parameters: - • buffer (number) - buffer number - • NOTE: Cannot be used with {pattern} + {id} Integer The id returned by nvim_create_autocmd - • pattern (string|table) - optional, defaults to - "*". - • NOTE: Cannot be used with {buffer} + See also: ~ + |nvim_create_autocmd()| - • group (string|int) - autocmd group name or id - • modeline (boolean) - Default true, see - |<nomodeline>| +nvim_do_autocmd({event}, {*opts}) *nvim_do_autocmd()* + Execute an autocommand |autocmd-execute|. + + Parameters: ~ + {event} (String|Array) The event or events to execute + {opts} Dictionary of autocommand options: + • group (string|integer) optional: the + autocommand group name or id to match against. + |autocmd-groups|. + • pattern (string|array) optional: defaults to + "*" |autocmd-pattern|. Cannot be used with + {buffer}. + • buffer (integer) optional: buffer number + |autocmd-buflocal|. Cannot be used with + {pattern}. + • modeline (bool) optional: defaults to true. + Process the modeline after the autocommands + |<nomodeline>|. -nvim_get_autocmds({*opts}) *nvim_get_autocmds()* - Get autocmds that match the requirements passed to {opts}. + See also: ~ + |:doautocmd| - Parameters: ~ - {opts} Optional Parameters: - • event : Name or list of name of events to match - against - • group (string|int): Name or id of group to match - against - • pattern: Pattern or list of patterns to match - against. Cannot be used with {buffer} - • buffer: Buffer number or list of buffer numbers - for buffer local autocommands - |autocmd-buflocal|. Cannot be used with - {pattern} +nvim_get_autocmds({*opts}) *nvim_get_autocmds()* + Get autocommands that match the requirements passed to {opts}. + + These examples will get autocommands matching ALL the given + criteria: > + -- Matches all criteria + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + event = {"BufEnter", "BufWinEnter"}, + pattern = {"*.c", "*.h"} + }) + + -- All commands from one group + autocommands = vim.api.nvim_get_autocmds({ + group = "MyGroup", + }) +< - Return: ~ - A list of autocmds that match + NOTE: When multiple patterns or events are provided, it will + find all the autocommands that match any combination of them. + + Parameters: ~ + {opts} Dictionary with at least one of the following: + • group (string|integer): the autocommand group + name or id to match against. + • event (string|array): event or events to match + against |autocmd-events|. + • pattern (string|array): pattern or patterns to + match against |autocmd-pattern|. + + Return: ~ + Array of autocommands matching the criteria, with each + item containing the following fields: + • id (number): the autocommand id (only when defined with + the API). + • group (integer): the autocommand group id. + • desc (string): the autocommand description. + • event (string): the autocommand event. + • command (string): the autocommand command. + • once (boolean): whether the autocommand is only run + once. + • pattern (string): the autocommand pattern. If the + autocommand is buffer local |autocmd-buffer-local|: + • buflocal (boolean): true if the autocommand is buffer + local. + • buffer (number): the buffer number. ============================================================================== |