mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-09-22 11:18:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(api): improve autocommand docs (#17545)

Browse Source 
[skip ci]
This commit is contained in:
Javier Lopez
2022-03-25 13:24:53 -05:00
committed by GitHub
parent 5e64d65df6
commit 174deafcef
2 changed files with 291 additions and 157 deletions
Download Patch File Download Diff File Expand all files Collapse all files

247
runtime/doc/api.txt
View File

@@ -3152,129 +3152,206 @@ nvim_tabpage_set_var({tabpage}, {name}, {value})
Autocmd Functions *api-autocmd* Autocmd Functions *api-autocmd*
nvim_create_augroup({name}, {*opts}) *nvim_create_augroup()* 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: > To get an existing group id, do: >
local id = vim.api.nvim_create_augroup(name, { local id = vim.api.nvim_create_augroup("MyGroup", {
clear = false clear = false
}) })
< <
Parameters: ~ Parameters: ~
{name} String: The name of the augroup to create {name} String: The name of the group
{opts} Parameters {opts} Dictionary Parameters
• clear (bool): Whether to clear existing commands • clear (bool) optional: defaults to true. Clear
or not. Defaults to true. See |autocmd-groups| existing commands if the group already exists
|autocmd-groups|.
Return: ~ 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()* nvim_create_autocmd({event}, {*opts}) *nvim_create_autocmd()*
Create an autocmd. Create an |autocommand|
Examples: The API allows for two (mutually exclusive) types of actions
• event: "pat1,pat2,pat3", to be executed when the autocommand triggers: a callback
• event: "pat1" function (Lua or Vimscript), or a command (like regular
• event: { "pat1" } autocommands).
• event: { "pat1", "pat2", "pat3" }
Example using callback: >
-- Lua function
local myluafun = function() print("This buffer enters") end
-- Vimscript function name (as a string)
local myvimfun = "g:MyVimFunction"
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'",
})
<
Example values for pattern: >
pattern = "*.py"
pattern = { "*.py", "*.pyi" }
<
Examples values for event: >
event = "BufPreWrite"
event = {"CursorHold", "BufPreWrite", "BufPostWrite"}
<
Parameters: ~ Parameters: ~
{event} The event or events to register this autocmd {event} (String|Array) The event or events to register
Required keys: event: string | ArrayOf(string) this autocommand
{opts} Dictionary of autocommand options:
Parameters: ~ • group (string|integer) optional: the
{opts} Optional Parameters: autocommand group name or id to match against.
• callback: (string|function) • pattern (string|array) optional: pattern or
• (string): The name of the viml function to patterns to match against |autocmd-pattern|.
execute when triggering this autocmd • buffer (integer) optional: buffer number for
• (function): The lua function to execute when buffer local autocommands |autocmd-buflocal|.
triggering this autocmd Cannot be used with {pattern}.
• NOTE: Cannot be used with {command} • desc (string) optional: description of the
autocommand.
• command: (string) command • callback (function|string) optional: Lua
• vimscript command function or Vim function (as string) to execute
• NOTE: Cannot be used with {callback} Eg. on event. Cannot be used with {command}
command = "let g:value_set = v:true" • command (string) optional: Vim command to
execute on event. Cannot be used with
• pattern: (string|table) {callback}
• pattern or patterns to match against • once (boolean) optional: defaults to false. Run
• defaults to "*". the autocommand only once |autocmd-once|.
• NOTE: Cannot be used with {buffer} • nested (boolean) optional: defaults to false.
Run nested autocommands |autocmd-nested|.
• buffer: (bufnr)
• create a |autocmd-buflocal| autocmd.
• NOTE: Cannot be used with {pattern}
• group: (string|int) The augroup name or id
• once: (boolean) - See |autocmd-once|
• nested: (boolean) - See |autocmd-nested|
• desc: (string) - Description of the autocmd
Return: ~ Return: ~
opaque value to use with nvim_del_autocmd Integer id of the created autocommand.
See also: ~
|autocommand|
|nvim_del_autocmd()|
nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()* nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()*
Delete an augroup by {id}. {id} can only be returned when Delete an autocommand group by id.
augroup was created with |nvim_create_augroup|.
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 NOTE: behavior differs from |augroup-delete|. When deleting a
will also be deleted and cleared. This augroup will no longer group, autocommands contained in this group will also be
exist deleted and cleared. This group will no longer exist.
Parameters: ~
{id} Integer The id of the group.
See also: ~
|nvim_del_augroup_by_name()|
|nvim_create_augroup()|
nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()* nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
Delete an augroup by {name}. Delete an autocommand group by name.
NOTE: behavior differs from augroup-delete. 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.
When deleting an augroup, autocmds contained by this augroup Parameters: ~
will also be deleted and cleared. This augroup will no longer {name} String The name of the group.
exist
See also: ~
|autocommand-groups|
nvim_del_autocmd({id}) *nvim_del_autocmd()* nvim_del_autocmd({id}) *nvim_del_autocmd()*
Delete an autocmd by {id}. Autocmds only return IDs when Delete an autocommand by id.
created via the API. Will not error if called and no autocmds
match the {id}. NOTE: Only autocommands created via the API have an id.
Parameters: ~ Parameters: ~
{id} Integer The ID returned by nvim_create_autocmd {id} Integer The id returned by nvim_create_autocmd
See also: ~
|nvim_create_autocmd()|
nvim_do_autocmd({event}, {*opts}) *nvim_do_autocmd()* nvim_do_autocmd({event}, {*opts}) *nvim_do_autocmd()*
Do one autocmd. Execute an autocommand |autocmd-execute|.
Parameters: ~ Parameters: ~
{event} The event or events to execute {event} (String|Array) The event or events to execute
{opts} Optional Parameters: {opts} Dictionary of autocommand options:
• buffer (number) - buffer number • group (string|integer) optional: the
• NOTE: Cannot be used with {pattern} 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>|.
• pattern (string|table) - optional, defaults to See also: ~
"*". |:doautocmd|
• NOTE: Cannot be used with {buffer}
• group (string|int) - autocmd group name or id
• modeline (boolean) - Default true, see
|<nomodeline>|
nvim_get_autocmds({*opts}) *nvim_get_autocmds()* nvim_get_autocmds({*opts}) *nvim_get_autocmds()*
Get autocmds that match the requirements passed to {opts}. 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",
})
<
NOTE: When multiple patterns or events are provided, it will
find all the autocommands that match any combination of them.
Parameters: ~ Parameters: ~
{opts} Optional Parameters: {opts} Dictionary with at least one of the following:
• event : Name or list of name of events to match • group (string|integer): the autocommand group
against name or id to match against.
• group (string|int): Name or id of group to match • event (string|array): event or events to match
against against |autocmd-events|.
• pattern: Pattern or list of patterns to match • pattern (string|array): pattern or patterns to
against. Cannot be used with {buffer} match against |autocmd-pattern|.
• buffer: Buffer number or list of buffer numbers
for buffer local autocommands
|autocmd-buflocal|. Cannot be used with
{pattern}
Return: ~ Return: ~
A list of autocmds that match 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.
============================================================================== ==============================================================================

201
src/nvim/api/autocmd.c
View File

@@ -36,16 +36,42 @@
// Used to delete autocmds from nvim_del_autocmd // Used to delete autocmds from nvim_del_autocmd
static int64_t next_autocmd_id = 1; static int64_t next_autocmd_id = 1;
/// Get autocmds that match the requirements passed to {opts}. /// Get autocommands that match the requirements passed to {opts}.
/// ///
/// @param opts Optional Parameters: /// These examples will get autocommands matching ALL the given criteria:
/// - event : Name or list of name of events to match against /// <pre>
/// - group (string|int): Name or id of group to match against /// -- Matches all criteria
/// - pattern: Pattern or list of patterns to match against. Cannot be used with {buffer} /// autocommands = vim.api.nvim_get_autocmds({
/// - buffer: Buffer number or list of buffer numbers for buffer local autocommands /// group = "MyGroup",
/// |autocmd-buflocal|. Cannot be used with {pattern} /// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"}
/// })
/// ///
/// @return A list of autocmds that match /// -- All commands from one group
/// autocommands = vim.api.nvim_get_autocmds({
/// group = "MyGroup",
/// })
/// </pre>
///
/// NOTE: When multiple patterns or events are provided, it will find all the autocommands that
/// match any combination of them.
///
/// @param 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.
Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err) Array nvim_get_autocmds(Dict(get_autocmds) *opts, Error *err)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
{ {
@@ -301,40 +327,68 @@ cleanup:
return autocmd_list; return autocmd_list;
} }
/// Create an autocmd. /// Create an |autocommand|
/// ///
/// @param event The event or events to register this autocmd /// The API allows for two (mutually exclusive) types of actions to be executed when the autocommand
/// Required keys: /// triggers: a callback function (Lua or Vimscript), or a command (like regular autocommands).
/// event: string | ArrayOf(string)
/// ///
/// Examples: /// Example using callback:
/// - event: "pat1,pat2,pat3", /// <pre>
/// - event: "pat1" /// -- Lua function
/// - event: { "pat1" } /// local myluafun = function() print("This buffer enters") end
/// - event: { "pat1", "pat2", "pat3" }
/// ///
/// @param opts Optional Parameters: /// -- Vimscript function name (as a string)
/// - callback: (string|function) /// local myvimfun = "g:MyVimFunction"
/// - (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}
/// - command: (string) command
/// - vimscript command
/// - NOTE: Cannot be used with {callback}
/// Eg. command = "let g:value_set = v:true"
/// - pattern: (string|table)
/// - pattern or patterns to match against
/// - defaults to "*".
/// - NOTE: Cannot be used with {buffer}
/// - buffer: (bufnr)
/// - create a |autocmd-buflocal| autocmd.
/// - NOTE: Cannot be used with {pattern}
/// - group: (string|int) The augroup name or id
/// - once: (boolean) - See |autocmd-once|
/// - nested: (boolean) - See |autocmd-nested|
/// - desc: (string) - Description of the autocmd
/// ///
/// @returns opaque value to use with nvim_del_autocmd /// vim.api.nvim_create_autocmd({
/// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"},
/// callback = myluafun, -- Or myvimfun
/// })
/// </pre>
///
/// Example using command:
/// <pre>
/// vim.api.nvim_create_autocmd({
/// event = {"BufEnter", "BufWinEnter"},
/// pattern = {"*.c", "*.h"},
/// command = "echo 'Entering a C or C++ file'",
/// })
/// </pre>
///
/// Example values for pattern:
/// <pre>
/// pattern = "*.py"
/// pattern = { "*.py", "*.pyi" }
/// </pre>
///
/// Examples values for event:
/// <pre>
/// event = "BufPreWrite"
/// event = {"CursorHold", "BufPreWrite", "BufPostWrite"}
/// </pre>
///
/// @param event (String|Array) The event or events to register this autocommand
/// @param 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.
/// @see |autocommand|
/// @see |nvim_del_autocmd()|
Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autocmd) *opts, Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autocmd) *opts,
Error *err) Error *err)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
@@ -552,33 +606,32 @@ cleanup:
return autocmd_id; return autocmd_id;
} }
/// Delete an autocmd by {id}. Autocmds only return IDs when created /// Delete an autocommand by id.
/// via the API. Will not error if called and no autocmds match
/// the {id}.
/// ///
/// @param id Integer The ID returned by nvim_create_autocmd /// NOTE: Only autocommands created via the API have an id.
/// @param id Integer The id returned by nvim_create_autocmd
/// @see |nvim_create_autocmd()|
void nvim_del_autocmd(Integer id) void nvim_del_autocmd(Integer id)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
{ {
autocmd_delete_id(id); autocmd_delete_id(id);
} }
/// Create or get an augroup. /// Create or get an autocommand group |autocmd-groups|.
/// ///
/// To get an existing augroup ID, do: /// To get an existing group id, do:
/// <pre> /// <pre>
/// local id = vim.api.nvim_create_augroup(name, { /// local id = vim.api.nvim_create_augroup("MyGroup", {
/// clear = false /// clear = false
/// }) /// })
/// </pre> /// </pre>
/// ///
/// @param name String: The name of the augroup to create /// @param name String: The name of the group
/// @param opts Parameters /// @param opts Dictionary Parameters
/// - clear (bool): Whether to clear existing commands or not. /// - clear (bool) optional: defaults to true. Clear existing
/// Defaults to true. /// commands if the group already exists |autocmd-groups|.
/// See |autocmd-groups| /// @return Integer id of the created group.
/// /// @see |autocmd-groups|
/// @returns opaque value to use with nvim_del_augroup_by_id
Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augroup) *opts, Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augroup) *opts,
Error *err) Error *err)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
@@ -604,13 +657,15 @@ Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augrou
return augroup; return augroup;
} }
/// Delete an augroup by {id}. {id} can only be returned when augroup was /// Delete an autocommand group by id.
/// created with |nvim_create_augroup|.
/// ///
/// 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. /// NOTE: behavior differs from |augroup-delete|. When deleting a group, autocommands contained in
/// This augroup will no longer exist /// this group will also be deleted and cleared. This group will no longer exist.
/// @param id Integer The id of the group.
/// @see |nvim_del_augroup_by_name()|
/// @see |nvim_create_augroup()|
void nvim_del_augroup_by_id(Integer id) void nvim_del_augroup_by_id(Integer id)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
{ {
@@ -618,28 +673,30 @@ void nvim_del_augroup_by_id(Integer id)
augroup_del(name, false); augroup_del(name, false);
} }
/// Delete an augroup by {name}. /// Delete an autocommand group by name.
/// ///
/// NOTE: behavior differs from augroup-delete. /// 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.
/// When deleting an augroup, autocmds contained by this augroup will also be deleted and cleared. /// @param name String The name of the group.
/// This augroup will no longer exist /// @see |autocommand-groups|
void nvim_del_augroup_by_name(String name) void nvim_del_augroup_by_name(String name)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
{ {
augroup_del(name.data, false); augroup_del(name.data, false);
} }
/// Do one autocmd. /// Execute an autocommand |autocmd-execute|.
/// /// @param event (String|Array) The event or events to execute
/// @param event The event or events to execute /// @param opts Dictionary of autocommand options:
/// @param opts Optional Parameters: /// - group (string|integer) optional: the autocommand group name or
/// - buffer (number) - buffer number /// id to match against. |autocmd-groups|.
/// - NOTE: Cannot be used with {pattern} /// - pattern (string|array) optional: defaults to "*" |autocmd-pattern|. Cannot be used
/// - pattern (string|table) - optional, defaults to "*". /// with {buffer}.
/// - NOTE: Cannot be used with {buffer} /// - buffer (integer) optional: buffer number |autocmd-buflocal|. Cannot be used with
/// - group (string|int) - autocmd group name or id /// {pattern}.
/// - modeline (boolean) - Default true, see |<nomodeline>| /// - modeline (bool) optional: defaults to true. Process the
/// modeline after the autocommands |<nomodeline>|.
/// @see |:doautocmd|
void nvim_do_autocmd(Object event, Dict(do_autocmd) *opts, Error *err) void nvim_do_autocmd(Object event, Dict(do_autocmd) *opts, Error *err)
FUNC_API_SINCE(9) FUNC_API_SINCE(9)
{ {