From 02ce4465103addbe5839e96d4efc6aeca8c8a1e5 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 17 Mar 2026 17:02:15 -0400 Subject: [PATCH] docs: api, lsp, messages, intro #38327 --- runtime/doc/api.txt | 255 ++++++++++++++------------- runtime/doc/autocmd.txt | 15 +- runtime/doc/lsp.txt | 25 ++- runtime/doc/options.txt | 72 ++++---- runtime/lua/vim/_meta/api.lua | 210 ++++++++++------------ runtime/lua/vim/_meta/options.lua | 72 ++++---- src/nvim/api/autocmd.c | 185 +++++++++---------- src/nvim/api/tabpage.c | 2 +- src/nvim/api/vim.c | 49 ++--- src/nvim/options.lua | 72 ++++---- test/functional/api/autocmd_spec.lua | 6 +- test/functional/ui/messages_spec.lua | 29 +-- 12 files changed, 496 insertions(+), 496 deletions(-) diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 2255470dfa..54e6b862a1 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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) (not expanded to a full path) - • match: (string) (expanded to a full path) - • buf: (number) - • data: (any) arbitrary data passed from + • group: (`number?`) Group id, if any + • file: (`string`) (not expanded to a full path) + • match: (`string`) (expanded to a full path) + • buf: (`number`) + • 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 . - • 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 . + • 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 diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index 3b9c98a343..f5c6ccd83f 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -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 diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index a64d70ac56..1f666118c1 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -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 diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt index 266e95d55a..db07548b0b 100644 --- a/runtime/doc/options.txt +++ b/runtime/doc/options.txt @@ -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") diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 3057cd8998..c3a7170b07 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -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) [] (not expanded to a full path) ---- - match: (string) [] (expanded to a full path) ---- - buf: (number) [] ---- - 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`) [] (not expanded to a full path) +--- - match: (`string`) [] (expanded to a full path) +--- - buf: (`number`) [] +--- - 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 []. ---- - 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 +--- []. +--- - 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 # 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 diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua index 5e0c52bf7e..d63b3821db 100644 --- a/runtime/lua/vim/_meta/options.lua +++ b/runtime/lua/vim/_meta/options.lua @@ -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" diff --git a/src/nvim/api/autocmd.c b/src/nvim/api/autocmd.c index f75076f66a..34d88d8a5f 100644 --- a/src/nvim/api/autocmd.c +++ b/src/nvim/api/autocmd.c @@ -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) [] (not expanded to a full path) -/// - match: (string) [] (expanded to a full path) -/// - buf: (number) [] -/// - 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`) [] (not expanded to a full path) +/// - match: (`string`) [] (expanded to a full path) +/// - buf: (`number`) [] +/// - 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 []. -/// - 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 +/// []. +/// - 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; }); diff --git a/src/nvim/api/tabpage.c b/src/nvim/api/tabpage.c index 48aa743c30..7754a7d4c7 100644 --- a/src/nvim/api/tabpage.c +++ b/src/nvim/api/tabpage.c @@ -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 { diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c index 63c01bf519..e1ba6caa78 100644 --- a/src/nvim/api/vim.c +++ b/src/nvim/api/vim.c @@ -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; }); diff --git a/src/nvim/options.lua b/src/nvim/options.lua index 5b816662a4..4b4ba69a57 100644 --- a/src/nvim/options.lua +++ b/src/nvim/options.lua @@ -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', diff --git a/test/functional/api/autocmd_spec.lua b/test/functional/api/autocmd_spec.lua index 2324b9ffea..1d513f4213 100644 --- a/test/functional/api/autocmd_spec.lua +++ b/test/functional/api/autocmd_spec.lua @@ -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, diff --git a/test/functional/ui/messages_spec.lua b/test/functional/ui/messages_spec.lua index 2b8e54b2a6..13bf17e6c9 100644 --- a/test/functional/ui/messages_spec.lua +++ b/test/functional/ui/messages_spec.lua @@ -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' } },