mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2026-03-27 19:02:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: api, lsp, messages, intro #38327

Browse Source
This commit is contained in:
Justin M. Keyes
2026-03-17 17:02:15 -04:00
committed by GitHub
parent 0da9827673
commit 02ce446510
12 changed files with 496 additions and 496 deletions
Download Patch File Download Diff File Expand all files Collapse all files

255
runtime/doc/api.txt
View File

@@ -658,7 +658,14 @@ nvim_del_var({name}) *nvim_del_var()*
• {name} (`string`) Variable name
nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
Prints a message given by a list of `[text, hl_group]` "chunks".
Prints a message given by a list of `[text, hl_group]` "chunks". Emits a
|Progress| event if `kind='progress'`.
Returns a message-id, which can be given in later calls to update an
existing message. The message-id is an autogenerated integer, or a
user-defined string. The id "address space" is global, so plugins
specifying a string id should use qualified names such as "my.msg.id" to
avoid unintentional conflicts.
Example: >lua
vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {})
@@ -673,30 +680,33 @@ nvim_echo({chunks}, {history}, {opts}) *nvim_echo()*
(optional) name or ID `hl_group`.
• {history} (`boolean`) if true, add to |message-history|.
• {opts} (`vim.api.keyset.echo_opts`) Optional parameters.
• id: message id for updating existing message.
• err: Treat the message like `:echoerr`. Sets `hl_group`
to |hl-ErrorMsg| by default.
• kind: Set the |ui-messages| kind with which this message
will be emitted.
• verbose: Message is controlled by the 'verbose' option.
Nvim invoked with `-V3log` will write the message to the
"log" file instead of standard output.
• title: The title for |progress-message|.
• status: Current status of the |progress-message|. Can be
one of the following values
• success: The progress item completed successfully
• running: The progress is ongoing
• failed: The progress item failed
• cancel: The progressing process should be canceled.
NOTE: Cancel must be handled by progress initiator by
listening for the `Progress` event
• percent: How much progress is done on the progress
message
• data: dictionary containing additional information
• data (`table?`) Dict of arbitrary data, available in
|Progress| |event-data|.
• err (`boolean?`) Treat the message like `:echoerr`. Sets
`hl_group` to |hl-ErrorMsg| by default.
• id (`integer|string?`) Message-id returned by a previous
`nvim_echo` call, or a user-defined id (string). If
existing message has this id, it will be updated instead
of creating a new message.
• kind (`string?`) Decides the |ui-messages| kind in the
emitted message. Set "progress" to emit a
|progress-message|.
• percent (`integer?`) |progress-message| percentage.
• status (`string?`) |progress-message| status:
• "success": Process completed successfully.
• "running": Process is ongoing.
• "failed": Process failed.
• "cancel": Process should be cancelled. Progress owner
must handle the |Progress| event to perform the
cancellation.
• title (`string?`) Message title. Only for
|progress-message| currently.
• verbose (`boolean?`) Message is controlled by the
'verbose' option. `nvim -V3log` will write the message to
the "log" file instead of standard output.
Return: ~
(`integer|string`) Message id.
• -1 means nvim_echo didn't show a message
(`integer|string`) Message-id, or -1 if message wasn't shown.
nvim_eval_statusline({str}, {opts}) *nvim_eval_statusline()*
Evaluates statusline string.
@@ -2007,39 +2017,35 @@ nvim_parse_expression({expr}, {flags}, {highlight})
Autocmd Functions *api-autocmd*
nvim_clear_autocmds({opts}) *nvim_clear_autocmds()*
Clears all autocommands selected by {opts}. To delete autocmds see
Clears all autocommands matching the {opts} query. To delete autocmds see
|nvim_del_autocmd()|.
Attributes: ~
Since: 0.7.0
Parameters: ~
• {opts} (`vim.api.keyset.clear_autocmds`) Parameters
• event: (vim.api.keyset.events|vim.api.keyset.events[])
• {opts} (`vim.api.keyset.clear_autocmds`) Optional parameters:
• event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
Examples:
• event: "pat1"
• event: { "pat1" }
• event: { "pat1", "pat2", "pat3" }
• pattern: (string|table)
• pattern or patterns to match exactly.
• For example, if you have `*.py` as that pattern for the
autocmd, you must pass `*.py` exactly to clear it.
`test.py` will not match the pattern.
• defaults to clearing all patterns.
• NOTE: Cannot be used with {buffer}
• buffer: (bufnr)
• clear only |autocmd-buflocal| autocommands.
• NOTE: Cannot be used with {pattern}
• group: (string|int) The augroup name or id.
• NOTE: If not passed, will only delete autocmds not in any
group.
• pattern: (`string|table?`) Filter by patterns (exact match).
Not allowed with {buffer}.
• Example: if you have `*.py` as that pattern for the
autocmd, you must pass `*.py` exactly to clear it.
`test.py` will not match the pattern.
• buffer: (`integer?`) Select |autocmd-buflocal| autocommands.
Not allowed with {pattern}.
• group: (`string|int?`) Group name or id.
• NOTE: If not given, matches autocmds not in any group.
nvim_create_augroup({name}, {opts}) *nvim_create_augroup()*
Create or get an autocommand group |autocmd-groups|.
To get an existing group id, do: >lua
local id = vim.api.nvim_create_augroup('my.lsp.config', {
clear = false
clear = false
})
<
@@ -2047,13 +2053,13 @@ nvim_create_augroup({name}, {opts}) *nvim_create_augroup()*
Since: 0.7.0
Parameters: ~
• {name} (`string`) String: The name of the group
• {opts} (`vim.api.keyset.create_augroup`) Dict Parameters
• clear (bool) optional: defaults to true. Clear existing
commands if the group already exists |autocmd-groups|.
• {name} (`string`) Group name
• {opts} (`vim.api.keyset.create_augroup`) Optional parameters:
• clear (`boolean?`, default: true) Clear existing commands in
the group |autocmd-groups|.
Return: ~
(`integer`) Integer id of the created group.
(`integer`) Group id.
See also: ~
• |autocmd-groups|
@@ -2091,36 +2097,34 @@ nvim_create_autocmd({event}, {opts}) *nvim_create_autocmd()*
• {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s)
that will trigger the handler (`callback` or `command`).
• {opts} (`vim.api.keyset.create_autocmd`) 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 (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 a truthy
value (not `false` or `nil`) to delete the autocommand, and
receives one argument, a table with these keys:
*event-args*
• id: (number) autocommand id
• event: (vim.api.keyset.events) name of the triggered
• buffer (`integer?`) Buffer id for buffer-local autocommands
|autocmd-buflocal|. Not allowed with {pattern}.
• callback (`function|string?`) Lua function (or Vimscript
function name, if string) called when the event(s) is
triggered. Lua callback can return |lua-truthy| to delete
the autocommand. Callback receives one argument, a table
with keys: *event-args*
• id: (`number`) Autocommand id
• event: (`vim.api.keyset.events`) Name of the triggered
event |autocmd-events|
• group: (number|nil) autocommand group id, if any
• file: (string) <afile> (not expanded to a full path)
• match: (string) <amatch> (expanded to a full path)
• buf: (number) <abuf>
• data: (any) arbitrary data passed from
• group: (`number?`) Group id, if any
• file: (`string`) <afile> (not expanded to a full path)
• match: (`string`) <amatch> (expanded to a full path)
• buf: (`number`) <abuf>
• data: (`any`) Arbitrary data passed from
|nvim_exec_autocmds()| *event-data*
• 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|.
• command (string?) Vim command executed on event. Not
allowed with {callback}.
• desc (`string?`) Description (for documentation and
troubleshooting).
• group (`string|integer?`) Group name or id to match
against.
• nested (`boolean?`, default: false) Run nested autocommands
|autocmd-nested|.
• once (`boolean?`, default: false) Handle the event only
once |autocmd-once|.
• pattern (`string|array?`) Pattern(s) to match literally
|autocmd-pattern|.
Return: ~
(`integer`) Autocommand id (number)
@@ -2142,7 +2146,7 @@ nvim_del_augroup_by_id({id}) *nvim_del_augroup_by_id()*
Since: 0.7.0
Parameters: ~
• {id} (`integer`) Integer The id of the group.
• {id} (`integer`) Group id.
See also: ~
• |nvim_del_augroup_by_name()|
@@ -2159,7 +2163,7 @@ nvim_del_augroup_by_name({name}) *nvim_del_augroup_by_name()*
Since: 0.7.0
Parameters: ~
• {name} (`string`) String The name of the group.
• {name} (`string`) Group name.
See also: ~
• |autocmd-groups|
@@ -2171,38 +2175,40 @@ nvim_del_autocmd({id}) *nvim_del_autocmd()*
Since: 0.7.0
Parameters: ~
• {id} (`integer`) Integer Autocommand id returned by
|nvim_create_autocmd()|
• {id} (`integer`) Autocommand id returned by |nvim_create_autocmd()|
nvim_exec_autocmds({event}, {opts}) *nvim_exec_autocmds()*
Execute all autocommands for {event} that match the corresponding {opts}
|autocmd-execute|.
Executes handlers for {event} that match the corresponding {opts} query.
|autocmd-execute|
Attributes: ~
Since: 0.7.0
Parameters: ~
• {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) The event
or events to execute
• {opts} (`vim.api.keyset.exec_autocmds`) Dict 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>.
• data (any): arbitrary data to send to the autocommand
callback. See |nvim_create_autocmd()| for details.
• {event} (`vim.api.keyset.events|vim.api.keyset.events[]`) Event(s) to
execute.
• {opts} (`vim.api.keyset.exec_autocmds`) Optional filters:
• group (`string|integer?`) Group name or id to match
against. |autocmd-groups|.
• pattern (`string|array?`, default: "*") |autocmd-pattern|.
Not allowed with {buffer}.
• buffer (`integer?`) Buffer id |autocmd-buflocal|. Not
allowed with {pattern}.
• modeline (`boolean?`, default: true) Process the modeline
after the autocommands <nomodeline>.
• data (`any`): Arbitrary data passed to the callback. See
|nvim_create_autocmd()|.
See also: ~
• |:doautocmd|
nvim_get_autocmds({opts}) *nvim_get_autocmds()*
Get all autocommands that match the corresponding {opts}.
Gets all autocommands matching ALL criteria in the {opts} query.
These examples will get autocommands matching ALL the given criteria: >lua
Note: When multiple patterns or events are provided they have "OR"
semantics (any combination is matched).
Examples: >lua
-- Matches all criteria
autocommands = vim.api.nvim_get_autocmds({
group = 'MyGroup',
@@ -2216,44 +2222,39 @@ nvim_get_autocmds({opts}) *nvim_get_autocmds()*
})
<
NOTE: When multiple patterns or events are provided, it will find all the
autocommands that match any combination of them.
Attributes: ~
Since: 0.7.0
Parameters: ~
• {opts} (`vim.api.keyset.get_autocmds`) Dict with at least one of the
following:
• buffer: (integer) Buffer number or list of buffer numbers
for buffer local autocommands |autocmd-buflocal|. Cannot be
used with {pattern}
• event: (vim.api.keyset.events|vim.api.keyset.events[]) event
or events to match against |autocmd-events|.
• id: (integer) Autocommand ID to match.
• group: (string|table) the autocommand group name or id to
match against.
• pattern: (string|table) pattern or patterns to match against
|autocmd-pattern|. Cannot be used with {buffer}
• {opts} (`vim.api.keyset.get_autocmds`) Dict with at least one of
these keys:
• buffer: (`integer[]|integer?`) Buffer id or list of buffer
ids, for buffer-local autocommands |autocmd-buflocal|. Not
allowed with {pattern}.
• event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
Event(s) to match |autocmd-events|.
• group: (`string|table?`) Group name or id to match.
• id: (`integer?`) Autocommand ID to match.
• pattern: (`string|table?`) Pattern(s) to match
|autocmd-pattern|. Not allowed with {buffer}.
Return: ~
(`vim.api.keyset.get_autocmds.ret[]`) Array of autocommands matching
the criteria, with each item containing the following fields:
• buffer: (integer) the buffer number.
• buflocal: (boolean) true if the autocommand is buffer local.
• command: (string) the autocommand command. Note: this will be empty
if a callback is set.
• callback: (function|string|nil): Lua function or name of a Vim
script function which is executed when this autocommand is
triggered.
• desc: (string) the autocommand description.
• event: (vim.api.keyset.events) the autocommand event.
• id: (integer) the autocommand id (only when defined with the API).
• group: (integer) the autocommand group id.
• group_name: (string) the autocommand group name.
• once: (boolean) whether the autocommand is only run once.
• pattern: (string) the autocommand pattern. If the autocommand is
buffer local |autocmd-buffer-local|:
(`vim.api.keyset.get_autocmds.ret[]`) Array of matching autocommands,
where each item has:
• buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
• buflocal (`boolean?`): true if the autocommand is buffer-local
|autocmd-buffer-local|.
• callback: (`function|string?`): Event handler: a Lua function or
Vimscript function name.
• command: (`string`) Event handler: an Ex-command. Empty if a
`callback` is set.
• desc: (`string`) Description.
• event: (`vim.api.keyset.events`) Event name(s).
• group: (`integer`) Group id.
• group_name: (`string`) Group name.
• id: (`integer`) Autocommand id (only when defined with the API).
• once: (`boolean`) true if |autocmd-once| was set.
• pattern: (`string`) Autocommand pattern.
==============================================================================
@@ -3556,7 +3557,7 @@ nvim_open_tabpage({buffer}, {enter}, {config}) *nvim_open_tabpage()*
current). 0 = first, N = after Nth.
Return: ~
(`integer`) Tabpage handle of the created tabpage
(`integer`) |tab-ID| of the new tabpage
nvim_tabpage_del_var({tabpage}, {name}) *nvim_tabpage_del_var()*
Removes a tab-scoped (t:) variable

15
runtime/doc/autocmd.txt
View File

@@ -818,7 +818,7 @@ ModeChanged After changing the mode. The pattern is
:au ModeChanged *:[vV\x16]* let &l:rnu = mode() =~# '^[vV\x16]'
:au WinEnter,WinLeave * let &l:rnu = mode() =~# '^[vV\x16]'
Progress *Progress*
After a progress message is created or updated via
After a |progress-message| is created or updated via
`nvim_echo`. The pattern is matched against
title of the message. The |event-data| contains:
id: id of the message
@@ -828,19 +828,16 @@ Progress *Progress*
percent: how much progress has been
made for this progress item
Usage example:
>
>lua
vim.api.nvim_create_autocmd('Progress', {
pattern={"term"},
pattern={'term'},
callback = function(ev)
print(string.format('event fired: %s', vim.inspect(ev)))
end
})
local id = vim.api.nvim_echo({{'searching...'}}, true,
{kind='progress', status='running', percent=10, title="term"})
vim.api.nvim_echo({{'searching'}}, true,
{id = id, kind='progress', status='running', percent=50, title="term"})
vim.api.nvim_echo({{'done'}}, true,
{id = id, kind='progress', status='success', percent=100, title="term"})
local id = vim.api.nvim_echo({{'searching...'}}, true, {kind='progress', status='running', percent=10, title='term'})
vim.api.nvim_echo({{'searching'}}, true, {id = id, kind='progress', status='running', percent=50, title='term'})
vim.api.nvim_echo({{'done'}}, true, {id = id, kind='progress', status='success', percent=100, title='term'})
< *OptionSet*
OptionSet After setting an option (except during

25
runtime/doc/lsp.txt
View File

@@ -68,15 +68,16 @@ Follow these steps to get LSP features:
==============================================================================
DEFAULTS *lsp-defaults*
When the Nvim LSP client starts it enables diagnostics |vim.diagnostic| (see
|vim.diagnostic.config()| to customize). It also sets various default options,
listed below, if (1) the language server supports the functionality and (2)
the options are empty or were set by the builtin runtime (ftplugin) files. The
options are not restored when the LSP client is stopped or detached.
When LSP activates, by default it enables various LSP features and sets
options and keymaps, listed below, if (1) the language server supports the
functionality and (2) the options are empty or were set by the builtin runtime
(ftplugin) files. The options are not restored when the LSP client is stopped
or detached.
GLOBAL DEFAULTS *gra* *gri* *grn* *grr* *grt* *i_CTRL-S*
These GLOBAL keymaps are created unconditionally when Nvim starts:
- "gra" (Normal and Visual mode) is mapped to |vim.lsp.buf.code_action()|
- "gri" is mapped to |vim.lsp.buf.implementation()|
- "grn" is mapped to |vim.lsp.buf.rename()|
@@ -93,6 +94,20 @@ These GLOBAL keymaps are created unconditionally when Nvim starts:
"os"
)
<
These LSP features are enabled by default:
- Diagnostics |lsp-diagnostic|. See |vim.diagnostic.config()| to customize.
- `workspace/didChangeWatchedFiles` (except on Linux). If you see poor
performance in big workspaces, run `:checkhealth vim.lsp` and look for "file
watching". Try disabling file-watching: >lua
local capabilities = vim.lsp.protocol.make_client_capabilities()
if capabilities.workspace then
capabilities.workspace.didChangeWatchedFiles = nil
end
vim.lsp.config('*', {
capabilities = capabilities,
})
<
BUFFER-LOCAL DEFAULTS

72
runtime/doc/options.txt
View File

@@ -3232,33 +3232,39 @@ A jump table for the options with a short description can be found at |Q_op|.
This is a scanf-like string that uses the same format as the
'errorformat' option: see |errorformat|.
If ripgrep ('grepprg') is available, this option defaults to `%f:%l:%c:%m`.
Defaults to "%f:%l:%c:%m" if ripgrep ('grepprg') is available.
*'grepprg'* *'gp'*
'grepprg' 'gp' string (default see below)
global or local to buffer |global-local|
Program to use for the |:grep| command. This option may contain '%'
and '#' characters, which are expanded like when used in a command-
line. The placeholder "$*" is allowed to specify where the arguments
will be included. Environment variables are expanded |:set_env|. See
|option-backslash| about including spaces and backslashes.
Program to use for the |:grep| command.
Note: if you change this then you must also update 'grepformat'.
May contain "%" and "#" characters, are expanded per |cmdline-special|.
The placeholder "$*" specifies where the arguments will be included.
Environment variables are expanded |:set_env|. See |option-backslash|
about including spaces and backslashes.
Special value: When 'grepprg' is set to "internal" the |:grep| command
works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like
|:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|.
See also the section |:make_makeprg|, since most of the comments there
apply equally to 'grepprg'.
See also |:make_makeprg|, most of the comments there apply to 'grepprg'.
Defaults to:
- "rg --vimgrep -uu " if ripgrep is available (|:checkhealth|),
- "grep -HIn $* /dev/null" on Unix,
- "findstr /n $* nul" on Windows.
Ripgrep may perform additional filtering such as using .gitignore rules
and skipping hidden files. This is disabled by default (via "-u") to
more closely match the behaviour of standard grep.
You can make ripgrep match Vim's case handling using the
-i/--ignore-case and -S/--smart-case options. Handle |OptionSet| to
dynamically update 'grepprg' when e.g. 'ignorecase' is changed.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
This option defaults to:
- `rg --vimgrep -uu ` if ripgrep is available (|:checkhealth|),
- `grep -HIn $* /dev/null` on Unix,
- `findstr /n $* nul` on Windows.
Ripgrep can perform additional filtering such as using .gitignore rules
and skipping hidden files. This is disabled by default (see the -u option)
to more closely match the behaviour of standard grep.
You can make ripgrep match Vim's case handling using the
-i/--ignore-case and -S/--smart-case options.
An |OptionSet| autocmd can be used to set it up to match automatically.
*'guicursor'* *'gcr'* *E545* *E546* *E548* *E549*
'guicursor' 'gcr' string (default "n-v-c-sm:block,i-ci-ve:ver25,r-cr-o:hor20,t:block-blinkon500-blinkoff500-TermCursor")
@@ -4372,26 +4378,26 @@ A jump table for the options with a short description can be found at |Q_op|.
Option settings for outputting messages. It can consist of the
following items. Items must be separated by a comma.
hit-enter Use a |hit-enter| prompt when the message is longer than
'cmdheight' size.
wait:{n} Instead of using a |hit-enter| prompt, simply wait for
{n} milliseconds so that the user has a chance to read
the message. The maximum value of {n} is 10000. Use
0 to disable the wait (but then the user may miss an
important message).
This item is ignored when "hit-enter" is present, but
required when "hit-enter" is not present.
history:{n} Determines how many entries are remembered in the
|:messages| history. The maximum value is 10000.
Setting it to zero clears the message history.
This item must always be present.
progress:{s}
Determines where to show progress messages.
hit-enter Use a |hit-enter| prompt when the message is longer than
'cmdheight' size.
progress:{s} Determines where to show progress messages.
Valid values are:
empty: progress messages are hidden in cmdline.
"c": progress messages are shown in cmdline.
- empty: Progress messages not shown in cmdline.
- "c": Progress messages are shown in cmdline.
wait:{n} Deprecated with |ui2|.
Instead of a |hit-enter| prompt, simply wait for {n}
milliseconds so the user has a chance to read the
message. Maximum {n} is 10000. Use 0 to disable the
wait (user won't see any "hit-enter" messages).
Ignored when "hit-enter" is present, but required when
"hit-enter" is not present.
*'mkspellmem'* *'msm'*
'mkspellmem' 'msm' string (default "460000,2000,500")

210
runtime/lua/vim/_meta/api.lua generated
View File

@@ -831,26 +831,20 @@ function vim.api.nvim_call_function(fn, args) end
--- @param data string Data to write. 8-bit clean: may contain NUL bytes.
function vim.api.nvim_chan_send(chan, data) end
--- Clears all autocommands selected by {opts}. To delete autocmds see `nvim_del_autocmd()`.
--- Clears all autocommands matching the {opts} query. To delete autocmds see `nvim_del_autocmd()`.
---
--- @param opts vim.api.keyset.clear_autocmds Parameters
--- - event: (vim.api.keyset.events|vim.api.keyset.events[])
--- Examples:
--- - event: "pat1"
--- - event: { "pat1" }
--- - event: { "pat1", "pat2", "pat3" }
--- - pattern: (string|table)
--- - pattern or patterns to match exactly.
--- - For example, if you have `*.py` as that pattern for the autocmd,
--- you must pass `*.py` exactly to clear it. `test.py` will not
--- match the pattern.
--- - defaults to clearing all patterns.
--- - NOTE: Cannot be used with {buffer}
--- - buffer: (bufnr)
--- - clear only `autocmd-buflocal` autocommands.
--- - NOTE: Cannot be used with {pattern}
--- - group: (string|int) The augroup name or id.
--- - NOTE: If not passed, will only delete autocmds *not* in any group.
--- @param opts vim.api.keyset.clear_autocmds Optional parameters:
--- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
--- Examples:
--- - event: "pat1"
--- - event: { "pat1" }
--- - event: { "pat1", "pat2", "pat3" }
--- - pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buffer}.
--- - Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py`
--- exactly to clear it. `test.py` will not match the pattern.
--- - buffer: (`integer?`) Select `autocmd-buflocal` autocommands. Not allowed with {pattern}.
--- - group: (`string|int?`) Group name or id.
--- - NOTE: If not given, matches autocmds *not* in any group.
function vim.api.nvim_clear_autocmds(opts) end
--- Executes an Ex command `cmd`, specified as a Dict with the same structure as returned by
@@ -906,16 +900,15 @@ function vim.api.nvim_command_output(command) end
---
--- ```lua
--- local id = vim.api.nvim_create_augroup('my.lsp.config', {
--- clear = false
--- clear = false
--- })
--- ```
---
--- @see `:help autocmd-groups`
--- @param name string String: The name of the group
--- @param opts vim.api.keyset.create_augroup Dict Parameters
--- - clear (bool) optional: defaults to true. Clear existing
--- commands if the group already exists `autocmd-groups`.
--- @return integer # Integer id of the created group.
--- @param name string Group name
--- @param opts vim.api.keyset.create_augroup Optional parameters:
--- - clear (`boolean?`, default: true) Clear existing commands in the group `autocmd-groups`.
--- @return integer # Group id.
function vim.api.nvim_create_augroup(name, opts) end
--- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript
@@ -952,28 +945,24 @@ function vim.api.nvim_create_augroup(name, opts) end
--- @see vim.api.nvim_del_autocmd
--- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) that will trigger the handler (`callback` or `command`).
--- @param opts vim.api.keyset.create_autocmd 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 (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 a truthy
--- value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
--- table with these keys: [event-args]()
--- - id: (number) autocommand id
--- - event: (vim.api.keyset.events) name of the triggered event `autocmd-events`
--- - group: (number|nil) autocommand group id, if any
--- - file: (string) [<afile>] (not expanded to a full path)
--- - match: (string) [<amatch>] (expanded to a full path)
--- - buf: (number) [<abuf>]
--- - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
--- - 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`.
--- - buffer (`integer?`) Buffer id for buffer-local autocommands `autocmd-buflocal`.
--- Not allowed with {pattern}.
--- - callback (`function|string?`) Lua function (or Vimscript function name, if string)
--- called when the event(s) is triggered. Lua callback can return `lua-truthy` to delete
--- the autocommand. Callback receives one argument, a table with keys: [event-args]()
--- - id: (`number`) Autocommand id
--- - event: (`vim.api.keyset.events`) Name of the triggered event `autocmd-events`
--- - group: (`number?`) Group id, if any
--- - file: (`string`) [<afile>] (not expanded to a full path)
--- - match: (`string`) [<amatch>] (expanded to a full path)
--- - buf: (`number`) [<abuf>]
--- - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
--- - command (string?) Vim command executed on event. Not allowed with {callback}.
--- - desc (`string?`) Description (for documentation and troubleshooting).
--- - group (`string|integer?`) Group name or id to match against.
--- - nested (`boolean?`, default: false) Run nested autocommands `autocmd-nested`.
--- - once (`boolean?`, default: false) Handle the event only once `autocmd-once`.
--- - pattern (`string|array?`) Pattern(s) to match literally `autocmd-pattern`.
--- @return integer # Autocommand id (number)
function vim.api.nvim_create_autocmd(event, opts) end
@@ -1047,7 +1036,7 @@ function vim.api.nvim_create_user_command(name, command, opts) end
--- this group will also be deleted and cleared. This group will no longer exist.
--- @see vim.api.nvim_del_augroup_by_name
--- @see vim.api.nvim_create_augroup
--- @param id integer Integer The id of the group.
--- @param id integer Group id.
function vim.api.nvim_del_augroup_by_id(id) end
--- Delete an autocommand group by name.
@@ -1055,12 +1044,12 @@ function vim.api.nvim_del_augroup_by_id(id) end
--- 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.
--- @see `:help autocmd-groups`
--- @param name string String The name of the group.
--- @param name string Group name.
function vim.api.nvim_del_augroup_by_name(name) end
--- Deletes an autocommand by id.
---
--- @param id integer Integer Autocommand id returned by `nvim_create_autocmd()`
--- @param id integer Autocommand id returned by `nvim_create_autocmd()`
function vim.api.nvim_del_autocmd(id) end
--- Deletes the current line.
@@ -1097,7 +1086,13 @@ function vim.api.nvim_del_user_command(name) end
--- @param name string Variable name
function vim.api.nvim_del_var(name) end
--- Prints a message given by a list of `[text, hl_group]` "chunks".
--- Prints a message given by a list of `[text, hl_group]` "chunks". Emits a `Progress` event if
--- `kind='progress'`.
---
--- Returns a message-id, which can be given in later calls to update an existing message. The
--- message-id is an autogenerated integer, or a user-defined string. The id "address space" is
--- global, so plugins specifying a string id should use qualified names such as "my.msg.id" to
--- avoid unintentional conflicts.
---
--- Example:
--- ```lua
@@ -1108,23 +1103,24 @@ function vim.api.nvim_del_var(name) end
--- the (optional) name or ID `hl_group`.
--- @param history boolean if true, add to `message-history`.
--- @param opts vim.api.keyset.echo_opts Optional parameters.
--- - id: message id for updating existing message.
--- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
--- - kind: Set the `ui-messages` kind with which this message will be emitted.
--- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
--- will write the message to the "log" file instead of standard output.
--- - title: The title for `progress-message`.
--- - status: Current status of the `progress-message`. Can be
--- one of the following values
--- - success: The progress item completed successfully
--- - running: The progress is ongoing
--- - failed: The progress item failed
--- - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by
--- progress initiator by listening for the `Progress` event
--- - percent: How much progress is done on the progress message
--- - data: dictionary containing additional information
--- @return integer|string # Message id.
--- - -1 means nvim_echo didn't show a message
--- - data (`table?`) Dict of arbitrary data, available in `Progress` `event-data`.
--- - err (`boolean?`) Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default.
--- - id (`integer|string?`) Message-id returned by a previous `nvim_echo` call, or
--- a user-defined id (string). If existing message has this id, it will be updated
--- instead of creating a new message.
--- - kind (`string?`) Decides the `ui-messages` kind in the emitted message. Set "progress"
--- to emit a `progress-message`.
--- - percent (`integer?`) `progress-message` percentage.
--- - status (`string?`) `progress-message` status:
--- - "success": Process completed successfully.
--- - "running": Process is ongoing.
--- - "failed": Process failed.
--- - "cancel": Process should be cancelled. Progress owner must handle the `Progress`
--- event to perform the cancellation.
--- - title (`string?`) Message title. Only for `progress-message` currently.
--- - verbose (`boolean?`) Message is controlled by the 'verbose' option. `nvim -V3log` will write the
--- message to the "log" file instead of standard output.
--- @return integer|string # Message-id, or -1 if message wasn't shown.
function vim.api.nvim_echo(chunks, history, opts) end
--- @deprecated
@@ -1194,21 +1190,16 @@ function vim.api.nvim_exec(src, output) end
--- - output: (string|nil) Output if `opts.output` is true.
function vim.api.nvim_exec2(src, opts) end
--- Execute all autocommands for {event} that match the corresponding
--- {opts} `autocmd-execute`.
--- Executes handlers for {event} that match the corresponding {opts} query. `autocmd-execute`
--- @see `:help :doautocmd`
--- @param event vim.api.keyset.events|vim.api.keyset.events[] The event or events to execute
--- @param opts vim.api.keyset.exec_autocmds Dict 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>].
--- - data (any): arbitrary data to send to the autocommand callback. See
--- `nvim_create_autocmd()` for details.
--- @param event vim.api.keyset.events|vim.api.keyset.events[] Event(s) to execute.
--- @param opts vim.api.keyset.exec_autocmds Optional filters:
--- - group (`string|integer?`) Group name or id to match against. `autocmd-groups`.
--- - pattern (`string|array?`, default: "*") `autocmd-pattern`. Not allowed with {buffer}.
--- - buffer (`integer?`) Buffer id `autocmd-buflocal`. Not allowed with {pattern}.
--- - modeline (`boolean?`, default: true) Process the modeline after the autocommands
--- [<nomodeline>].
--- - data (`any`): Arbitrary data passed to the callback. See `nvim_create_autocmd()`.
function vim.api.nvim_exec_autocmds(event, opts) end
--- Sends input-keys to Nvim, subject to various quirks controlled by `mode`
@@ -1246,9 +1237,12 @@ function vim.api.nvim_feedkeys(keys, mode, escape_ks) end
--- @return table<string,any> # dict of all options
function vim.api.nvim_get_all_options_info() end
--- Get all autocommands that match the corresponding {opts}.
--- Gets all autocommands matching ALL criteria in the {opts} query.
---
--- These examples will get autocommands matching ALL the given criteria:
--- Note: When multiple patterns or events are provided they have "OR" semantics (any combination
--- is matched).
---
--- Examples:
---
--- ```lua
--- -- Matches all criteria
@@ -1264,33 +1258,25 @@ function vim.api.nvim_get_all_options_info() end
--- })
--- ```
---
--- NOTE: When multiple patterns or events are provided, it will find all the autocommands that
--- match any combination of them.
---
--- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following:
--- - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
--- `autocmd-buflocal`. Cannot be used with {pattern}
--- - event: (vim.api.keyset.events|vim.api.keyset.events[])
--- event or events to match against `autocmd-events`.
--- - id: (integer) Autocommand ID to match.
--- - group: (string|table) the autocommand group name or id to match against.
--- - pattern: (string|table) pattern or patterns to match against `autocmd-pattern`.
--- Cannot be used with {buffer}
--- @return vim.api.keyset.get_autocmds.ret[] # Array of autocommands matching the criteria, with each item
--- containing the following fields:
--- - buffer: (integer) the buffer number.
--- - buflocal: (boolean) true if the autocommand is buffer local.
--- - command: (string) the autocommand command. Note: this will be empty if a callback is set.
--- - callback: (function|string|nil): Lua function or name of a Vim script function
--- which is executed when this autocommand is triggered.
--- - desc: (string) the autocommand description.
--- - event: (vim.api.keyset.events) the autocommand event.
--- - id: (integer) the autocommand id (only when defined with the API).
--- - group: (integer) the autocommand group id.
--- - group_name: (string) the autocommand group name.
--- - once: (boolean) whether the autocommand is only run once.
--- - pattern: (string) the autocommand pattern.
--- If the autocommand is buffer local |autocmd-buffer-local|:
--- @param opts vim.api.keyset.get_autocmds Dict with at least one of these keys:
--- - buffer: (`integer[]|integer?`) Buffer id or list of buffer ids, for buffer-local autocommands
--- `autocmd-buflocal`. Not allowed with {pattern}.
--- - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) Event(s) to match `autocmd-events`.
--- - group: (`string|table?`) Group name or id to match.
--- - id: (`integer?`) Autocommand ID to match.
--- - pattern: (`string|table?`) Pattern(s) to match `autocmd-pattern`. Not allowed with {buffer}.
--- @return vim.api.keyset.get_autocmds.ret[] # Array of matching autocommands, where each item has:
--- - buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
--- - buflocal (`boolean?`): true if the autocommand is buffer-local |autocmd-buffer-local|.
--- - callback: (`function|string?`): Event handler: a Lua function or Vimscript function name.
--- - command: (`string`) Event handler: an Ex-command. Empty if a `callback` is set.
--- - desc: (`string`) Description.
--- - event: (`vim.api.keyset.events`) Event name(s).
--- - group: (`integer`) Group id.
--- - group_name: (`string`) Group name.
--- - id: (`integer`) Autocommand id (only when defined with the API).
--- - once: (`boolean`) true if |autocmd-once| was set.
--- - pattern: (`string`) Autocommand pattern.
function vim.api.nvim_get_autocmds(opts) end
--- Gets information about a channel.
@@ -1681,7 +1667,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end
--- @param config vim.api.keyset.tabpage_config Configuration for the new tabpage. Keys:
--- - after: Position to insert tabpage (default: -1; after current).
--- 0 = first, N = after Nth.
--- @return integer # Tabpage handle of the created tabpage
--- @return integer # |tab-ID| of the new tabpage
function vim.api.nvim_open_tabpage(buffer, enter, config) end
--- Open a terminal instance in a buffer

72
runtime/lua/vim/_meta/options.lua generated
View File

@@ -3029,7 +3029,7 @@ vim.go.fs = vim.go.fsync
--- This is a scanf-like string that uses the same format as the
--- 'errorformat' option: see `errorformat`.
---
--- If ripgrep ('grepprg') is available, this option defaults to `%f:%l:%c:%m`.
--- Defaults to "%f:%l:%c:%m" if ripgrep ('grepprg') is available.
---
--- @type string
vim.o.grepformat = "%f:%l:%m,%f:%l%m,%f %l%m"
@@ -3039,28 +3039,34 @@ vim.bo.gfm = vim.bo.grepformat
vim.go.grepformat = vim.o.grepformat
vim.go.gfm = vim.go.grepformat
--- Program to use for the `:grep` command. This option may contain '%'
--- and '#' characters, which are expanded like when used in a command-
--- line. The placeholder "$*" is allowed to specify where the arguments
--- will be included. Environment variables are expanded `:set_env`. See
--- `option-backslash` about including spaces and backslashes.
--- Program to use for the `:grep` command.
--- Note: if you change this then you must also update 'grepformat'.
---
--- May contain "%" and "#" characters, are expanded per `cmdline-special`.
--- The placeholder "$*" specifies where the arguments will be included.
--- Environment variables are expanded `:set_env`. See `option-backslash`
--- about including spaces and backslashes.
---
--- Special value: When 'grepprg' is set to "internal" the `:grep` command
--- works like `:vimgrep`, `:lgrep` like `:lvimgrep`, `:grepadd` like
--- `:vimgrepadd` and `:lgrepadd` like `:lvimgrepadd`.
--- See also the section `:make_makeprg`, since most of the comments there
--- apply equally to 'grepprg'.
---
--- See also `:make_makeprg`, most of the comments there apply to 'grepprg'.
---
--- Defaults to:
--- - "rg --vimgrep -uu " if ripgrep is available (`:checkhealth`),
--- - "grep -HIn $* /dev/null" on Unix,
--- - "findstr /n $* nul" on Windows.
---
--- Ripgrep may perform additional filtering such as using .gitignore rules
--- and skipping hidden files. This is disabled by default (via "-u") to
--- more closely match the behaviour of standard grep.
--- You can make ripgrep match Vim's case handling using the
--- -i/--ignore-case and -S/--smart-case options. Handle `OptionSet` to
--- dynamically update 'grepprg' when e.g. 'ignorecase' is changed.
---
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
--- This option defaults to:
--- - `rg --vimgrep -uu ` if ripgrep is available (`:checkhealth`),
--- - `grep -HIn $* /dev/null` on Unix,
--- - `findstr /n $* nul` on Windows.
--- Ripgrep can perform additional filtering such as using .gitignore rules
--- and skipping hidden files. This is disabled by default (see the -u option)
--- to more closely match the behaviour of standard grep.
--- You can make ripgrep match Vim's case handling using the
--- -i/--ignore-case and -S/--smart-case options.
--- An `OptionSet` autocmd can be used to set it up to match automatically.
---
--- @type string
vim.o.grepprg = "grep -HIn $* /dev/null"
@@ -4446,26 +4452,26 @@ vim.go.mis = vim.go.menuitems
--- Option settings for outputting messages. It can consist of the
--- following items. Items must be separated by a comma.
---
--- hit-enter Use a `hit-enter` prompt when the message is longer than
--- 'cmdheight' size.
---
--- wait:{n} Instead of using a `hit-enter` prompt, simply wait for
--- {n} milliseconds so that the user has a chance to read
--- the message. The maximum value of {n} is 10000. Use
--- 0 to disable the wait (but then the user may miss an
--- important message).
--- This item is ignored when "hit-enter" is present, but
--- required when "hit-enter" is not present.
---
--- history:{n} Determines how many entries are remembered in the
--- `:messages` history. The maximum value is 10000.
--- Setting it to zero clears the message history.
--- This item must always be present.
--- progress:{s}
--- Determines where to show progress messages.
---
--- hit-enter Use a `hit-enter` prompt when the message is longer than
--- 'cmdheight' size.
---
--- progress:{s} Determines where to show progress messages.
--- Valid values are:
--- empty: progress messages are hidden in cmdline.
--- "c": progress messages are shown in cmdline.
--- - empty: Progress messages not shown in cmdline.
--- - "c": Progress messages are shown in cmdline.
---
--- wait:{n} Deprecated with `ui2`.
--- Instead of a `hit-enter` prompt, simply wait for {n}
--- milliseconds so the user has a chance to read the
--- message. Maximum {n} is 10000. Use 0 to disable the
--- wait (user won't see any "hit-enter" messages).
--- Ignored when "hit-enter" is present, but required when
--- "hit-enter" is not present.
---
--- @type string
vim.o.messagesopt = "hit-enter,history:500,progress:c"

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

@@ -44,9 +44,12 @@
// Used to delete autocmds from nvim_del_autocmd
static int64_t next_autocmd_id = 1;
/// Get all autocommands that match the corresponding {opts}.
/// Gets all autocommands matching ALL criteria in the {opts} query.
///
/// These examples will get autocommands matching ALL the given criteria:
/// Note: When multiple patterns or events are provided they have "OR" semantics (any combination
/// is matched).
///
/// Examples:
///
/// ```lua
/// -- Matches all criteria
@@ -62,33 +65,25 @@ static int64_t next_autocmd_id = 1;
/// })
/// ```
///
/// NOTE: When multiple patterns or events are provided, it will find all the autocommands that
/// match any combination of them.
///
/// @param opts Dict with at least one of the following:
/// - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands
/// |autocmd-buflocal|. Cannot be used with {pattern}
/// - event: (vim.api.keyset.events|vim.api.keyset.events[])
/// event or events to match against |autocmd-events|.
/// - id: (integer) Autocommand ID to match.
/// - group: (string|table) the autocommand group name or id to match against.
/// - pattern: (string|table) pattern or patterns to match against |autocmd-pattern|.
/// Cannot be used with {buffer}
/// @return Array of autocommands matching the criteria, with each item
/// containing the following fields:
/// - buffer: (integer) the buffer number.
/// - buflocal: (boolean) true if the autocommand is buffer local.
/// - command: (string) the autocommand command. Note: this will be empty if a callback is set.
/// - callback: (function|string|nil): Lua function or name of a Vim script function
/// which is executed when this autocommand is triggered.
/// - desc: (string) the autocommand description.
/// - event: (vim.api.keyset.events) the autocommand event.
/// - id: (integer) the autocommand id (only when defined with the API).
/// - group: (integer) the autocommand group id.
/// - group_name: (string) the autocommand group name.
/// - once: (boolean) whether the autocommand is only run once.
/// - pattern: (string) the autocommand pattern.
/// If the autocommand is buffer local |autocmd-buffer-local|:
/// @param opts Dict with at least one of these keys:
/// - buffer: (`integer[]|integer?`) Buffer id or list of buffer ids, for buffer-local autocommands
/// |autocmd-buflocal|. Not allowed with {pattern}.
/// - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`) Event(s) to match |autocmd-events|.
/// - group: (`string|table?`) Group name or id to match.
/// - id: (`integer?`) Autocommand ID to match.
/// - pattern: (`string|table?`) Pattern(s) to match |autocmd-pattern|. Not allowed with {buffer}.
/// @return Array of matching autocommands, where each item has:
/// - buffer (`integer?`): Buffer id (only for |autocmd-buffer-local|).
/// - buflocal (`boolean?`): true if the autocommand is buffer-local |autocmd-buffer-local|.
/// - callback: (`function|string?`): Event handler: a Lua function or Vimscript function name.
/// - command: (`string`) Event handler: an Ex-command. Empty if a `callback` is set.
/// - desc: (`string`) Description.
/// - event: (`vim.api.keyset.events`) Event name(s).
/// - group: (`integer`) Group id.
/// - group_name: (`string`) Group name.
/// - id: (`integer`) Autocommand id (only when defined with the API).
/// - once: (`boolean`) true if |autocmd-once| was set.
/// - pattern: (`string`) Autocommand pattern.
ArrayOf(DictAs(get_autocmds__ret)) nvim_get_autocmds(Dict(get_autocmds) *opts, Arena *arena,
Error *err)
FUNC_API_SINCE(9)
@@ -151,8 +146,8 @@ ArrayOf(DictAs(get_autocmds__ret)) nvim_get_autocmds(Dict(get_autocmds) *opts, A
}
}
VALIDATE((!HAS_KEY(opts, get_autocmds, pattern) || !HAS_KEY(opts, get_autocmds, buffer)),
"%s", "Cannot use both 'pattern' and 'buffer'", {
VALIDATE_CON((!HAS_KEY(opts, get_autocmds, pattern) || !HAS_KEY(opts, get_autocmds, buffer)),
"pattern", "buffer", {
goto cleanup;
});
@@ -361,28 +356,24 @@ cleanup:
///
/// @param event Event(s) that will trigger the handler (`callback` or `command`).
/// @param 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 (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 a truthy
/// value (not `false` or `nil`) to delete the autocommand, and receives one argument, a
/// table with these keys: [event-args]()
/// - id: (number) autocommand id
/// - event: (vim.api.keyset.events) name of the triggered event |autocmd-events|
/// - group: (number|nil) autocommand group id, if any
/// - file: (string) [<afile>] (not expanded to a full path)
/// - match: (string) [<amatch>] (expanded to a full path)
/// - buf: (number) [<abuf>]
/// - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
/// - 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|.
/// - buffer (`integer?`) Buffer id for buffer-local autocommands |autocmd-buflocal|.
/// Not allowed with {pattern}.
/// - callback (`function|string?`) Lua function (or Vimscript function name, if string)
/// called when the event(s) is triggered. Lua callback can return |lua-truthy| to delete
/// the autocommand. Callback receives one argument, a table with keys: [event-args]()
/// - id: (`number`) Autocommand id
/// - event: (`vim.api.keyset.events`) Name of the triggered event |autocmd-events|
/// - group: (`number?`) Group id, if any
/// - file: (`string`) [<afile>] (not expanded to a full path)
/// - match: (`string`) [<amatch>] (expanded to a full path)
/// - buf: (`number`) [<abuf>]
/// - data: (`any`) Arbitrary data passed from [nvim_exec_autocmds()] [event-data]()
/// - command (string?) Vim command executed on event. Not allowed with {callback}.
/// - desc (`string?`) Description (for documentation and troubleshooting).
/// - group (`string|integer?`) Group name or id to match against.
/// - nested (`boolean?`, default: false) Run nested autocommands |autocmd-nested|.
/// - once (`boolean?`, default: false) Handle the event only once |autocmd-once|.
/// - pattern (`string|array?`) Pattern(s) to match literally |autocmd-pattern|.
///
/// @return Autocommand id (number)
/// @see |autocommand|
@@ -401,8 +392,9 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
goto cleanup;
}
VALIDATE((!HAS_KEY(opts, create_autocmd, callback) || !HAS_KEY(opts, create_autocmd, command)),
"%s", "Cannot use both 'callback' and 'command'", {
VALIDATE_CON((!HAS_KEY(opts, create_autocmd, callback) || !HAS_KEY(opts, create_autocmd,
command)),
"callback", "command", {
goto cleanup;
});
@@ -436,7 +428,7 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
} else if (HAS_KEY(opts, create_autocmd, command)) {
handler_cmd = string_to_cstr(opts->command);
} else {
VALIDATE(false, "%s", "Required: 'command' or 'callback'", {
VALIDATE_R(false, "'command' or 'callback'", {
goto cleanup;
});
}
@@ -448,8 +440,7 @@ Integer nvim_create_autocmd(uint64_t channel_id, Object event, Dict(create_autoc
bool has_buffer = HAS_KEY(opts, create_autocmd, buffer);
VALIDATE((!HAS_KEY(opts, create_autocmd, pattern) || !has_buffer),
"%s", "Cannot use both 'pattern' and 'buffer' for the same autocmd", {
VALIDATE_CON((!HAS_KEY(opts, create_autocmd, pattern) || !has_buffer), "pattern", "buffer", {
goto cleanup;
});
@@ -506,7 +497,7 @@ cleanup:
/// Deletes an autocommand by id.
///
/// @param id Integer Autocommand id returned by |nvim_create_autocmd()|
/// @param id Autocommand id returned by |nvim_create_autocmd()|
void nvim_del_autocmd(Integer id, Error *err)
FUNC_API_SINCE(9)
{
@@ -518,26 +509,20 @@ void nvim_del_autocmd(Integer id, Error *err)
}
}
/// Clears all autocommands selected by {opts}. To delete autocmds see |nvim_del_autocmd()|.
/// Clears all autocommands matching the {opts} query. To delete autocmds see |nvim_del_autocmd()|.
///
/// @param opts Parameters
/// - event: (vim.api.keyset.events|vim.api.keyset.events[])
/// Examples:
/// - event: "pat1"
/// - event: { "pat1" }
/// - event: { "pat1", "pat2", "pat3" }
/// - pattern: (string|table)
/// - pattern or patterns to match exactly.
/// - For example, if you have `*.py` as that pattern for the autocmd,
/// you must pass `*.py` exactly to clear it. `test.py` will not
/// match the pattern.
/// - defaults to clearing all patterns.
/// - NOTE: Cannot be used with {buffer}
/// - buffer: (bufnr)
/// - clear only |autocmd-buflocal| autocommands.
/// - NOTE: Cannot be used with {pattern}
/// - group: (string|int) The augroup name or id.
/// - NOTE: If not passed, will only delete autocmds *not* in any group.
/// @param opts Optional parameters:
/// - event: (`vim.api.keyset.events|vim.api.keyset.events[]?`)
/// Examples:
/// - event: "pat1"
/// - event: { "pat1" }
/// - event: { "pat1", "pat2", "pat3" }
/// - pattern: (`string|table?`) Filter by patterns (exact match). Not allowed with {buffer}.
/// - Example: if you have `*.py` as that pattern for the autocmd, you must pass `*.py`
/// exactly to clear it. `test.py` will not match the pattern.
/// - buffer: (`integer?`) Select |autocmd-buflocal| autocommands. Not allowed with {pattern}.
/// - group: (`string|int?`) Group name or id.
/// - NOTE: If not given, matches autocmds *not* in any group.
///
void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
FUNC_API_SINCE(9)
@@ -555,8 +540,7 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
bool has_buffer = HAS_KEY(opts, clear_autocmds, buffer);
VALIDATE((!HAS_KEY(opts, clear_autocmds, pattern) || !has_buffer),
"%s", "Cannot use both 'pattern' and 'buffer'", {
VALIDATE_CON((!HAS_KEY(opts, clear_autocmds, pattern) || !has_buffer), "pattern", "buffer", {
return;
});
@@ -603,15 +587,14 @@ void nvim_clear_autocmds(Dict(clear_autocmds) *opts, Arena *arena, Error *err)
///
/// ```lua
/// local id = vim.api.nvim_create_augroup('my.lsp.config', {
/// clear = false
/// clear = false
/// })
/// ```
///
/// @param name String: The name of the group
/// @param opts Dict Parameters
/// - clear (bool) optional: defaults to true. Clear existing
/// commands if the group already exists |autocmd-groups|.
/// @return Integer id of the created group.
/// @param name Group name
/// @param opts Optional parameters:
/// - clear (`boolean?`, default: true) Clear existing commands in the group |autocmd-groups|.
/// @return Group id.
/// @see |autocmd-groups|
Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augroup) *opts,
Error *err)
@@ -644,7 +627,7 @@ Integer nvim_create_augroup(uint64_t channel_id, String name, Dict(create_augrou
///
/// 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.
/// @param id Integer The id of the group.
/// @param id Group id.
/// @see |nvim_del_augroup_by_name()|
/// @see |nvim_create_augroup()|
void nvim_del_augroup_by_id(Integer id, Error *err)
@@ -660,7 +643,7 @@ void nvim_del_augroup_by_id(Integer id, Error *err)
///
/// 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.
/// @param name String The name of the group.
/// @param name Group name.
/// @see |autocmd-groups|
void nvim_del_augroup_by_name(String name, Error *err)
FUNC_API_SINCE(9)
@@ -670,20 +653,15 @@ void nvim_del_augroup_by_name(String name, Error *err)
});
}
/// Execute all autocommands for {event} that match the corresponding
/// {opts} |autocmd-execute|.
/// @param event The event or events to execute
/// @param opts Dict 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>].
/// - data (any): arbitrary data to send to the autocommand callback. See
/// |nvim_create_autocmd()| for details.
/// Executes handlers for {event} that match the corresponding {opts} query. |autocmd-execute|
/// @param event Event(s) to execute.
/// @param opts Optional filters:
/// - group (`string|integer?`) Group name or id to match against. |autocmd-groups|.
/// - pattern (`string|array?`, default: "*") |autocmd-pattern|. Not allowed with {buffer}.
/// - buffer (`integer?`) Buffer id |autocmd-buflocal|. Not allowed with {pattern}.
/// - modeline (`boolean?`, default: true) Process the modeline after the autocommands
/// [<nomodeline>].
/// - data (`any`): Arbitrary data passed to the callback. See |nvim_create_autocmd()|.
/// @see |:doautocmd|
void nvim_exec_autocmds(Object event, Dict(exec_autocmds) *opts, Arena *arena, Error *err)
FUNC_API_SINCE(9)
@@ -724,8 +702,7 @@ void nvim_exec_autocmds(Object event, Dict(exec_autocmds) *opts, Arena *arena, E
bool has_buffer = false;
if (HAS_KEY(opts, exec_autocmds, buffer)) {
VALIDATE((!HAS_KEY(opts, exec_autocmds, pattern)),
"%s", "Cannot use both 'pattern' and 'buffer' for the same autocmd", {
VALIDATE_CON((!HAS_KEY(opts, exec_autocmds, pattern)), "pattern", "buffer", {
return;
});

2
src/nvim/api/tabpage.c
View File

@@ -198,7 +198,7 @@ Boolean nvim_tabpage_is_valid(Tabpage tabpage)
/// - after: Position to insert tabpage (default: -1; after current).
/// 0 = first, N = after Nth.
/// @param[out] err Error details, if any
/// @return Tabpage handle of the created tabpage
/// @return |tab-ID| of the new tabpage
Tabpage nvim_open_tabpage(Buffer buffer, Boolean enter, Dict(tabpage_config) *config, Error *err)
FUNC_API_SINCE(14) FUNC_API_TEXTLOCK_ALLOW_CMDWIN
{

49
src/nvim/api/vim.c
View File

@@ -789,7 +789,13 @@ void nvim_set_vvar(String name, Object value, Error *err)
dict_set_var(get_vimvar_dict(), name, value, false, false, NULL, err);
}
/// Prints a message given by a list of `[text, hl_group]` "chunks".
/// Prints a message given by a list of `[text, hl_group]` "chunks". Emits a |Progress| event if
/// `kind='progress'`.
///
/// Returns a message-id, which can be given in later calls to update an existing message. The
/// message-id is an autogenerated integer, or a user-defined string. The id "address space" is
/// global, so plugins specifying a string id should use qualified names such as "my.msg.id" to
/// avoid unintentional conflicts.
///
/// Example:
/// ```lua
@@ -800,26 +806,26 @@ void nvim_set_vvar(String name, Object value, Error *err)
/// the (optional) name or ID `hl_group`.
/// @param history if true, add to |message-history|.
/// @param opts Optional parameters.
/// - id: message id for updating existing message.
/// - err: Treat the message like `:echoerr`. Sets `hl_group` to |hl-ErrorMsg| by default.
/// - kind: Set the |ui-messages| kind with which this message will be emitted.
/// - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log`
/// will write the message to the "log" file instead of standard output.
/// - title: The title for |progress-message|.
/// - status: Current status of the |progress-message|. Can be
/// one of the following values
/// - success: The progress item completed successfully
/// - running: The progress is ongoing
/// - failed: The progress item failed
/// - cancel: The progressing process should be canceled. NOTE: Cancel must be handled by
/// progress initiator by listening for the `Progress` event
/// - percent: How much progress is done on the progress message
/// - data: dictionary containing additional information
/// @return Message id.
/// - -1 means nvim_echo didn't show a message
/// - data (`table?`) Dict of arbitrary data, available in |Progress| |event-data|.
/// - err (`boolean?`) Treat the message like `:echoerr`. Sets `hl_group` to |hl-ErrorMsg| by default.
/// - id (`integer|string?`) Message-id returned by a previous `nvim_echo` call, or
/// a user-defined id (string). If existing message has this id, it will be updated
/// instead of creating a new message.
/// - kind (`string?`) Decides the |ui-messages| kind in the emitted message. Set "progress"
/// to emit a |progress-message|.
/// - percent (`integer?`) |progress-message| percentage.
/// - status (`string?`) |progress-message| status:
/// - "success": Process completed successfully.
/// - "running": Process is ongoing.
/// - "failed": Process failed.
/// - "cancel": Process should be cancelled. Progress owner must handle the |Progress|
/// event to perform the cancellation.
/// - title (`string?`) Message title. Only for |progress-message| currently.
/// - verbose (`boolean?`) Message is controlled by the 'verbose' option. `nvim -V3log` will write the
/// message to the "log" file instead of standard output.
/// @return Message-id, or -1 if message wasn't shown.
Union(Integer, String) nvim_echo(ArrayOf(Tuple(String, *HLGroupID)) chunks, Boolean history,
Dict(echo_opts) *opts,
Error *err)
Dict(echo_opts) *opts, Error *err)
FUNC_API_SINCE(7)
{
MsgID id = INTEGER_OBJ(-1);
@@ -841,8 +847,7 @@ Union(Integer, String) nvim_echo(ArrayOf(Tuple(String, *HLGroupID)) chunks, Bool
VALIDATE(is_progress
|| (opts->status.size == 0 && opts->title.size == 0 && opts->percent == 0
&& opts->data.size == 0),
"%s",
"title, status, percent and data fields can only be used with progress messages",
"Conflict: title/status/percent/data not allowed with kind='%s'", kind,
{
goto error;
});

72
src/nvim/options.lua
View File

@@ -3850,7 +3850,7 @@ local options = {
This is a scanf-like string that uses the same format as the
'errorformat' option: see |errorformat|.
If ripgrep ('grepprg') is available, this option defaults to `%f:%l:%c:%m`.
Defaults to "%f:%l:%c:%m" if ripgrep ('grepprg') is available.
]=],
full_name = 'grepformat',
list = 'onecomma',
@@ -3868,28 +3868,34 @@ local options = {
doc = [[see below]],
},
desc = [=[
Program to use for the |:grep| command. This option may contain '%'
and '#' characters, which are expanded like when used in a command-
line. The placeholder "$*" is allowed to specify where the arguments
will be included. Environment variables are expanded |:set_env|. See
|option-backslash| about including spaces and backslashes.
Program to use for the |:grep| command.
Note: if you change this then you must also update 'grepformat'.
May contain "%" and "#" characters, are expanded per |cmdline-special|.
The placeholder "$*" specifies where the arguments will be included.
Environment variables are expanded |:set_env|. See |option-backslash|
about including spaces and backslashes.
Special value: When 'grepprg' is set to "internal" the |:grep| command
works like |:vimgrep|, |:lgrep| like |:lvimgrep|, |:grepadd| like
|:vimgrepadd| and |:lgrepadd| like |:lvimgrepadd|.
See also the section |:make_makeprg|, since most of the comments there
apply equally to 'grepprg'.
See also |:make_makeprg|, most of the comments there apply to 'grepprg'.
Defaults to:
- "rg --vimgrep -uu " if ripgrep is available (|:checkhealth|),
- "grep -HIn $* /dev/null" on Unix,
- "findstr /n $* nul" on Windows.
Ripgrep may perform additional filtering such as using .gitignore rules
and skipping hidden files. This is disabled by default (via "-u") to
more closely match the behaviour of standard grep.
You can make ripgrep match Vim's case handling using the
-i/--ignore-case and -S/--smart-case options. Handle |OptionSet| to
dynamically update 'grepprg' when e.g. 'ignorecase' is changed.
This option cannot be set from a |modeline| or in the |sandbox|, for
security reasons.
This option defaults to:
- `rg --vimgrep -uu ` if ripgrep is available (|:checkhealth|),
- `grep -HIn $* /dev/null` on Unix,
- `findstr /n $* nul` on Windows.
Ripgrep can perform additional filtering such as using .gitignore rules
and skipping hidden files. This is disabled by default (see the -u option)
to more closely match the behaviour of standard grep.
You can make ripgrep match Vim's case handling using the
-i/--ignore-case and -S/--smart-case options.
An |OptionSet| autocmd can be used to set it up to match automatically.
]=],
expand = true,
full_name = 'grepprg',
@@ -5785,26 +5791,26 @@ local options = {
Option settings for outputting messages. It can consist of the
following items. Items must be separated by a comma.
hit-enter Use a |hit-enter| prompt when the message is longer than
'cmdheight' size.
wait:{n} Instead of using a |hit-enter| prompt, simply wait for
{n} milliseconds so that the user has a chance to read
the message. The maximum value of {n} is 10000. Use
0 to disable the wait (but then the user may miss an
important message).
This item is ignored when "hit-enter" is present, but
required when "hit-enter" is not present.
history:{n} Determines how many entries are remembered in the
|:messages| history. The maximum value is 10000.
Setting it to zero clears the message history.
This item must always be present.
progress:{s}
Determines where to show progress messages.
hit-enter Use a |hit-enter| prompt when the message is longer than
'cmdheight' size.
progress:{s} Determines where to show progress messages.
Valid values are:
empty: progress messages are hidden in cmdline.
"c": progress messages are shown in cmdline.
- empty: Progress messages not shown in cmdline.
- "c": Progress messages are shown in cmdline.
wait:{n} Deprecated with |ui2|.
Instead of a |hit-enter| prompt, simply wait for {n}
milliseconds so the user has a chance to read the
message. Maximum {n} is 10000. Use 0 to disable the
wait (user won't see any "hit-enter" messages).
Ignored when "hit-enter" is present, but required when
"hit-enter" is not present.
]=],
full_name = 'messagesopt',
list = 'onecommacolon',

6
test/functional/api/autocmd_spec.lua
View File

@@ -17,7 +17,7 @@ describe('autocmd api', function()
describe('nvim_create_autocmd', function()
it('validation', function()
eq(
"Cannot use both 'callback' and 'command'",
"Conflict: 'callback' not allowed with 'command'",
pcall_err(api.nvim_create_autocmd, 'BufReadPost', {
pattern = '*.py,*.pyi',
command = "echo 'Should Have Errored",
@@ -25,7 +25,7 @@ describe('autocmd api', function()
})
)
eq(
"Cannot use both 'pattern' and 'buffer' for the same autocmd",
"Conflict: 'pattern' not allowed with 'buffer'",
pcall_err(api.nvim_create_autocmd, 'FileType', {
command = 'let g:called = g:called + 1',
buffer = 0,
@@ -1534,7 +1534,7 @@ describe('autocmd api', function()
describe('nvim_clear_autocmds', function()
it('validation', function()
eq(
"Cannot use both 'pattern' and 'buffer'",
"Conflict: 'pattern' not allowed with 'buffer'",
pcall_err(api.nvim_clear_autocmds, {
pattern = '*',
buffer = 42,

29
test/functional/ui/messages_spec.lua
View File

@@ -2545,13 +2545,14 @@ describe('pager', function()
exec_lua(
'_G.x = ...',
[[
Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud xercitation
ullamco laboris nisi ut
aliquip ex ea commodo consequat.]]
t.dedent [[
Lorem ipsum dolor sit amet, consectetur
adipisicing elit, sed do eiusmod tempor
incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud xercitation
ullamco laboris nisi ut
aliquip ex ea commodo consequat.
]]
)
end)
@@ -3504,7 +3505,7 @@ describe('progress-message', function()
}, 'Progress autocmd receives progress update')
end)
it('user-defined data in `data` field', function()
it('user-defined data', function()
api.nvim_echo({ { 'test-message' } }, true, {
kind = 'progress',
title = 'TestSuit',
@@ -3542,25 +3543,25 @@ describe('progress-message', function()
}, 'Progress autocmd receives progress messages')
end)
it('validates', function()
it('validation', function()
-- throws error if title, status, percent, data is used in non progress message
eq(
'title, status, percent and data fields can only be used with progress messages',
"Conflict: title/status/percent/data not allowed with kind='echo'",
t.pcall_err(api.nvim_echo, { { 'test-message' } }, false, { title = 'TestSuit' })
)
eq(
'title, status, percent and data fields can only be used with progress messages',
"Conflict: title/status/percent/data not allowed with kind='echo'",
t.pcall_err(api.nvim_echo, { { 'test-message' } }, false, { status = 'running' })
)
eq(
'title, status, percent and data fields can only be used with progress messages',
"Conflict: title/status/percent/data not allowed with kind='echo'",
t.pcall_err(api.nvim_echo, { { 'test-message' } }, false, { percent = 10 })
)
eq(
'title, status, percent and data fields can only be used with progress messages',
"Conflict: title/status/percent/data not allowed with kind='echo'",
t.pcall_err(api.nvim_echo, { { 'test-message' } }, false, { data = { tag = 'test' } })
)
@@ -3709,7 +3710,7 @@ describe('progress-message', function()
eq(13, id8)
end)
it('supports string ids', function()
it('accepts caller-defined id (string)', function()
-- string id works
local id = api.nvim_echo(
{ { 'supports str-id' } },