mirror of
https://github.com/neovim/neovim.git
synced 2026-08-29 10:31:48 +00:00
Javier Lopez
@@ -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).
|
||||
|
||||
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: ~
|
||||
{event} The event or events to register this autocmd
|
||||
Required keys: event: string | ArrayOf(string)
|
||||
|
||||
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}
|
||||
|
||||
• 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
|
||||
{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: ~
|
||||
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()*
|
||||
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.
|
||||
|
||||
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()*
|
||||
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. This augroup will no longer
|
||||
exist
|
||||
Parameters: ~
|
||||
{name} String The name of the group.
|
||||
|
||||
See also: ~
|
||||
|autocommand-groups|
|
||||
|
||||
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}.
|
||||
Delete an autocommand by id.
|
||||
|
||||
NOTE: Only autocommands created via the API have an id.
|
||||
|
||||
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()*
|
||||
Do one autocmd.
|
||||
Execute an autocommand |autocmd-execute|.
|
||||
|
||||
Parameters: ~
|
||||
{event} The event or events to execute
|
||||
{opts} Optional Parameters:
|
||||
• buffer (number) - buffer number
|
||||
• NOTE: Cannot be used with {pattern}
|
||||
{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>|.
|
||||
|
||||
• pattern (string|table) - optional, defaults to
|
||||
"*".
|
||||
• NOTE: Cannot be used with {buffer}
|
||||
|
||||
• group (string|int) - autocmd group name or id
|
||||
• modeline (boolean) - Default true, see
|
||||
|<nomodeline>|
|
||||
See also: ~
|
||||
|:doautocmd|
|
||||
|
||||
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: ~
|
||||
{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}
|
||||
{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: ~
|
||||
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.
|
||||
|
||||
|
||||
==============================================================================
|
||||
|
||||
Reference in New Issue
Block a user