From 8d55cc218cfed54136677398ca76c45987b15f29 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Sun, 24 Nov 2024 10:40:56 +0000 Subject: feat(keysets): teach Union and LuaRefOf --- runtime/lua/vim/_meta/api.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 3c9b9d4f44..acd12b353d 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1012,7 +1012,7 @@ function vim.api.nvim_create_namespace(name) end --- ``` --- --- @param name string Name of the new user command. Must begin with an uppercase letter. ---- @param command any Replacement command to execute when this user command is executed. When called +--- @param command string|fun(args: vim.api.keyset.create_user_command.command_args) Replacement command to execute when this user command is executed. When called --- from Lua, the command can also be a Lua function. The function is called with a --- single table argument that contains the following keys: --- - name: (string) Command name -- cgit From ae93c7f369a174f3d738ab55030de2c9dfc10c57 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Tue, 3 Dec 2024 09:44:28 -0800 Subject: docs: misc, help tags for neovim.io searches #31428 Problem: Various keywords are commonly searched-for on https://neovim.io, but don't have help tags. Solution: Add help tags. fix #31327 --- runtime/lua/vim/_meta/api.lua | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index acd12b353d..d74ee11b46 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1654,7 +1654,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- Open a terminal instance in a buffer --- --- By default (and currently the only option) the terminal will not be ---- connected to an external process. Instead, input send on the channel +--- connected to an external process. Instead, input sent on the channel --- will be echoed directly by the terminal. This is useful to display --- ANSI terminal sequences returned as part of a rpc message, or similar. --- @@ -1665,6 +1665,18 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- Then `nvim_chan_send()` can be called immediately to process sequences --- in a virtual terminal having the intended size. --- +--- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you +--- can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]() +--- +--- ```lua +--- vim.api.nvim_create_user_command('TermHl', function() +--- local b = vim.api.nvim_create_buf(false, true) +--- local chan = vim.api.nvim_open_term(b, {}) +--- vim.api.nvim_chan_send(chan, table.concat(vim.api.nvim_buf_get_lines(0, 0, -1, false), '\n')) +--- vim.api.nvim_win_set_buf(0, b) +--- end, { desc = 'Highlights ANSI termcodes in curbuf' }) +--- ``` +--- --- @param buffer integer the buffer to use (expected to be empty) --- @param opts vim.api.keyset.open_term Optional parameters. --- - on_input: Lua callback for input sent, i e keypresses in terminal -- cgit From e9f4ceeb7467364554ecef770fd3380e89457abb Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Fri, 6 Dec 2024 20:01:28 +0800 Subject: fix(events): don't expand `args.file` for Lua callback (#31473) Problem: In an autocommand Lua callback whether `args.file` is expanded depends on whether `expand('')` has been called. Solution: Always use the unexpanded file name for `args.file`. Related to #31306 and vim/vim#16106. This doesn't provide `sfname`, but at least makes `args.file` have a consistent value. --- runtime/lua/vim/_meta/api.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index d74ee11b46..b2385197bd 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -963,9 +963,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- - id: (number) autocommand id --- - event: (string) name of the triggered event `autocmd-events` --- - group: (number|nil) autocommand group id, if any ---- - match: (string) expanded value of [] ---- - buf: (number) expanded value of [] ---- - file: (string) expanded value of [] +--- - 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} -- cgit From 022449b5223659d515b78bada7de2fac8718820a Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Mon, 16 Dec 2024 08:34:16 -0800 Subject: fix(api): generic error messages, not using TRY_WRAP #31596 Problem: - API functions using `try_start` directly, do not surface the underlying error message, and instead show generic messages. - Error-handling code is duplicated in the API impl. - Failure modes are not tested. Solution: - Use `TRY_WRAP`. - Add tests. --- runtime/lua/vim/_meta/api.lua | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index b2385197bd..55274963ed 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -885,10 +885,8 @@ function vim.api.nvim_cmd(cmd, opts) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- ---- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate multiple lines of Vim script ---- or an Ex command directly, use `nvim_exec2()`. To construct an Ex command using a structured ---- format and then execute it, use `nvim_cmd()`. To modify an Ex command before evaluating it, use ---- `nvim_parse_cmd()` in conjunction with `nvim_cmd()`. +--- Prefer `nvim_cmd()` or `nvim_exec2()` instead. To modify an Ex command in a structured way +--- before executing it, modify the result of `nvim_parse_cmd()` then pass it to `nvim_cmd()`. --- --- @param command string Ex command string function vim.api.nvim_command(command) end -- cgit From a5a4149e9754a96c063a357c18397aa7906edf53 Mon Sep 17 00:00:00 2001 From: luukvbaal Date: Thu, 19 Dec 2024 16:04:33 +0100 Subject: docs(api): specify when decor provider on_buf is called #31634 --- runtime/lua/vim/_meta/api.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 55274963ed..8d759278d0 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -2134,8 +2134,8 @@ function vim.api.nvim_set_current_win(window) end --- ``` --- ["start", tick] --- ``` ---- - on_buf: called for each buffer being redrawn (before ---- window callbacks) +--- - on_buf: called for each buffer being redrawn (once per edit, +--- before window callbacks) --- ``` --- ["buf", bufnr, tick] --- ``` -- cgit From 8ef41f590224dfeea2e51d9fec150e363fd72ee0 Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 19 Dec 2024 07:07:04 -0800 Subject: feat(jobs): jobstart(…,{term=true}), deprecate termopen() #31343 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Problem: `termopen` has long been a superficial wrapper around `jobstart`, and has no real purpose. Also, `vim.system` and `nvim_open_term` presumably will replace all features of `jobstart` and `termopen`, so centralizing the logic will help with that. Solution: - Introduce `eval/deprecated.c`, where all deprecated eval funcs will live. - Introduce "term" flag of `jobstart`. - Deprecate `termopen`. --- runtime/lua/vim/_meta/api.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 8d759278d0..bea6df43bb 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -272,12 +272,12 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- This temporarily switches current buffer to "buffer". --- If the current window already shows "buffer", the window is not switched. --- If a window inside the current tabpage (including a float) already shows the ---- buffer, then one of these windows will be set as current window temporarily. +--- buffer, then one of those windows will be set as current window temporarily. --- Otherwise a temporary scratch window (called the "autocmd window" for --- historical reasons) will be used. --- --- This is useful e.g. to call Vimscript functions that only work with the ---- current buffer/window currently, like `termopen()`. +--- current buffer/window currently, like `jobstart(…, {'term': v:true})`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable -- cgit From b51110f4a11af114401e626cd4c1f1aec23e81c5 Mon Sep 17 00:00:00 2001 From: Shihua Zeng <76579810+Bekaboo@users.noreply.github.com> Date: Tue, 24 Dec 2024 12:56:10 -0500 Subject: docs(api): return type of nvim_get_keymap() #31708 --- runtime/lua/vim/_meta/api.lua | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index bea6df43bb..7297c8ad38 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -452,7 +452,7 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. --- The "buffer" key holds the associated buffer handle. function vim.api.nvim_buf_get_keymap(buffer, mode) end @@ -1414,7 +1414,7 @@ function vim.api.nvim_get_hl_ns(opts) end --- Gets a list of global (non-buffer-local) `mapping` definitions. --- --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. --- The "buffer" key is always zero. function vim.api.nvim_get_keymap(mode) end -- cgit From ead5683ff9994c0fbfc6c38e0911d9455777550b Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Tue, 7 Jan 2025 14:20:45 +0100 Subject: feat(api): add err field to nvim_echo() opts Problem: We want to deprecate `nvim_err_write(ln)()` but there is no obvious replacement (from Lua). Meanwhile we already have `nvim_echo()` with an `opts` argument. Solution: Add `err` argument to `nvim_echo()` that directly maps to `:echoerr`. --- runtime/lua/vim/_meta/api.lua | 2 ++ 1 file changed, 2 insertions(+) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 7297c8ad38..b0651efca4 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1104,6 +1104,8 @@ function vim.api.nvim_del_var(name) end --- `hl_group` element can be omitted for no highlight. --- @param history boolean if true, add to `message-history`. --- @param opts vim.api.keyset.echo_opts Optional parameters. +--- - err: Treat the message like `:echoerr`. Omitted `hlgroup` +--- uses `hl-ErrorMsg` instead. --- - verbose: Message is printed as a result of 'verbose' option. --- If Nvim was invoked with -V3log_file, the message will be --- redirected to the log_file and suppressed from direct output. -- cgit From 5c92b40b4b173c7d85106689fef811e41994abb0 Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Tue, 7 Jan 2025 16:38:29 +0100 Subject: feat(api): deprecate nvim_out/err_write(ln) --- runtime/lua/vim/_meta/api.lua | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index b0651efca4..f6d8153c27 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1111,17 +1111,12 @@ function vim.api.nvim_del_var(name) end --- redirected to the log_file and suppressed from direct output. function vim.api.nvim_echo(chunks, history, opts) end ---- Writes a message to the Vim error buffer. Does not append "\n", the ---- message is buffered (won't display) until a linefeed is written. ---- ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_err_write(str) end ---- Writes a message to the Vim error buffer. Appends "\n", so the buffer is ---- flushed (and displayed). ---- ---- @see vim.api.nvim_err_write ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_err_writeln(str) end --- Evaluates a Vimscript `expression`. Dicts and Lists are recursively expanded. @@ -1861,10 +1856,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- @return integer # Window handle, or 0 on error function vim.api.nvim_open_win(buffer, enter, config) end ---- Writes a message to the Vim output buffer. Does not append "\n", the ---- message is buffered (won't display) until a linefeed is written. ---- ---- @param str string Message +--- @deprecated +--- @param str string function vim.api.nvim_out_write(str) end --- Parse command line. -- cgit From 7c00e0efbb18e8627ac59eaadf564a9f1b2bafcd Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 9 Jan 2025 09:26:45 -0800 Subject: docs: misc #31867 --- runtime/lua/vim/_meta/api.lua | 37 +++++++++++++++++++++++++------------ 1 file changed, 25 insertions(+), 12 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index f6d8153c27..b5d8a0937d 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1097,18 +1097,20 @@ function vim.api.nvim_del_user_command(name) end --- @param name string Variable name function vim.api.nvim_del_var(name) end ---- Echo a message. +--- Prints a message given by a list of `[text, hl_group]` "chunks". --- ---- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a ---- text chunk with specified highlight group name or ID. ---- `hl_group` element can be omitted for no highlight. +--- Example: +--- ```lua +--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}) +--- ``` +--- +--- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highlighted by +--- 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. ---- - err: Treat the message like `:echoerr`. Omitted `hlgroup` ---- uses `hl-ErrorMsg` instead. ---- - verbose: Message is printed as a result of 'verbose' option. ---- If Nvim was invoked with -V3log_file, the message will be ---- redirected to the log_file and suppressed from direct output. +--- - err: Treat the message like `:echoerr`. Sets `hl_group` to `hl-ErrorMsg` by default. +--- - verbose: Message is controlled by the 'verbose' option. Nvim invoked with `-V3log` +--- will write the message to the "log" file instead of standard output. function vim.api.nvim_echo(chunks, history, opts) end --- @deprecated @@ -1276,6 +1278,8 @@ function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. --- +--- See `nvim_list_uis()` for an example of how to get channel info. +--- --- @param chan integer channel_id, or 0 for current channel --- @return table # Channel info dict with these keys: --- - "id" Channel id. @@ -1293,8 +1297,8 @@ function vim.api.nvim_get_autocmds(opts) end --- "/dev/pts/1". If unknown, the key will still be present if a pty is used (e.g. --- for conpty on Windows). --- - "buffer" (optional) Buffer connected to |terminal| instance. ---- - "client" (optional) Info about the peer (client on the other end of the RPC channel), ---- which it provided via |nvim_set_client_info()|. +--- - "client" (optional) Info about the peer (client on the other end of the channel), as set +--- by |nvim_set_client_info()|. --- function vim.api.nvim_get_chan_info(chan) end @@ -1616,6 +1620,14 @@ function vim.api.nvim_list_tabpages() end --- Gets a list of dictionaries representing attached UIs. --- +--- Example: The Nvim builtin `TUI` sets its channel info as described in `startup-tui`. In +--- particular, it sets `client.name` to "nvim-tui". So you can check if the TUI is running by +--- inspecting the client name of each UI: +--- +--- ```lua +--- vim.print(vim.api.nvim_get_chan_info(vim.api.nvim_list_uis()[1].chan).client.name) +--- ``` +--- --- @return any[] # Array of UI dictionaries, each with these keys: --- - "height" Requested height of the UI --- - "width" Requested width of the UI @@ -1661,7 +1673,8 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- in a virtual terminal having the intended size. --- --- Example: this `TermHl` command can be used to display and highlight raw ANSI termcodes, so you ---- can use Nvim as a "scrollback pager" (for terminals like kitty): [terminal-scrollback-pager]() +--- can use Nvim as a "scrollback pager" (for terminals like kitty): [ansi-colorize]() +--- [terminal-scrollback-pager]() --- --- ```lua --- vim.api.nvim_create_user_command('TermHl', function() -- cgit From 0717dfbfaf36887dab277527eb0a93bf2182297c Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Fri, 10 Jan 2025 11:42:04 -0800 Subject: refactor(api): deprecate nvim_notify #31938 Problem: The `nvim_notify` API (note: unrelated to `vim.notify()` Lua API) was not given any real motivation in https://github.com/neovim/neovim/pull/13843 There are, and were, idiomatic and ergonomic alternatives already. Solution: Deprecate `nvim_notify`. --- runtime/lua/vim/_meta/api.lua | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index b5d8a0937d..8930f131f6 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1647,14 +1647,10 @@ function vim.api.nvim_list_wins() end --- @return any function vim.api.nvim_load_context(dict) end ---- Notify the user with a message ---- ---- Relays the call to vim.notify . By default forwards your message in the ---- echo area but can be overridden to trigger desktop notifications. ---- ---- @param msg string Message to display to the user ---- @param log_level integer The log level ---- @param opts table Reserved for future use. +--- @deprecated +--- @param msg string +--- @param log_level integer +--- @param opts table --- @return any function vim.api.nvim_notify(msg, log_level, opts) end -- cgit From 25d8c3a5ad7e9c5668841e66540ebe34ceda73a7 Mon Sep 17 00:00:00 2001 From: luukvbaal Date: Tue, 14 Jan 2025 14:02:46 +0100 Subject: feat(api): nvim_open_win() relative to tabline and laststatus #32006 Problem: Anchoring a floating window to the tabline and laststatus is cumbersome; requiring autocommands and looping over all windows/tabpages. Solution: Add new "tabline" and "laststatus" options to the `relative` field of nvim_open_win() to place a window relative to. --- runtime/lua/vim/_meta/api.lua | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 8930f131f6..670e867c1e 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1754,10 +1754,12 @@ function vim.api.nvim_open_term(buffer, opts) end --- @param config vim.api.keyset.win_config Map defining the window configuration. Keys: --- - relative: Sets the window layout to "floating", placed at (row,col) --- coordinates relative to: ---- - "editor" The global editor grid ---- - "win" Window given by the `win` field, or current window. ---- - "cursor" Cursor position in current window. ---- - "mouse" Mouse position +--- - "cursor" Cursor position in current window. +--- - "editor" The global editor grid. +--- - "laststatus" 'laststatus' if present, or last row. +--- - "mouse" Mouse position. +--- - "tabline" Tabline if present, or first row. +--- - "win" Window given by the `win` field, or current window. --- - win: `window-ID` window to split, or relative window when creating a --- float (relative="win"). --- - anchor: Decides which corner of the float to place at (row,col): -- cgit From 19b25f3feacfedc18a57eb2a1368a1ed07ac5faa Mon Sep 17 00:00:00 2001 From: bfredl Date: Sun, 19 Jan 2025 13:30:11 +0100 Subject: feat(api): deprecate nvim_buf_add_highlight() This was kept for a while as it was a useful short hand and initially matched what highlights what actually properly implemented. But now |vim.hl.range()| is a better high-level shorthand with full support for native multi-line ranges. --- runtime/lua/vim/_meta/api.lua | 39 +++++++++------------------------------ 1 file changed, 9 insertions(+), 30 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 670e867c1e..4168d5b857 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -163,35 +163,14 @@ function vim.api.nvim__stats() end --- @return any function vim.api.nvim__unpack(str) end ---- Adds a highlight to buffer. ---- ---- Useful for plugins that dynamically generate highlights to a buffer ---- (like a semantic highlighter or linter). The function adds a single ---- highlight to a buffer. Unlike `matchaddpos()` highlights follow changes to ---- line numbering (as lines are inserted/removed above the highlighted line), ---- like signs and marks do. ---- ---- Namespaces are used for batch deletion/updating of a set of highlights. To ---- create a namespace, use `nvim_create_namespace()` which returns a namespace ---- id. Pass it in to this function as `ns_id` to add highlights to the ---- namespace. All highlights in the same namespace can then be cleared with ---- single call to `nvim_buf_clear_namespace()`. If the highlight never will be ---- deleted by an API call, pass `ns_id = -1`. ---- ---- As a shorthand, `ns_id = 0` can be used to create a new namespace for the ---- highlight, the allocated id is then returned. If `hl_group` is the empty ---- string no highlight is added, but a new `ns_id` is still returned. This is ---- supported for backwards compatibility, new code should use ---- `nvim_create_namespace()` to create a new empty namespace. ---- ---- @param buffer integer Buffer handle, or 0 for current buffer ---- @param ns_id integer namespace to use or -1 for ungrouped highlight ---- @param hl_group string Name of the highlight group to use ---- @param line integer Line to highlight (zero-indexed) ---- @param col_start integer Start of (byte-indexed) column range to highlight ---- @param col_end integer End of (byte-indexed) column range to highlight, ---- or -1 to highlight to end of line ---- @return integer # The ns_id that was used +--- @deprecated +--- @param buffer integer +--- @param ns_id integer +--- @param hl_group string +--- @param line integer +--- @param col_start integer +--- @param col_end integer +--- @return integer function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. @@ -987,7 +966,7 @@ function vim.api.nvim_create_buf(listed, scratch) end --- Creates a new namespace or gets an existing one. [namespace]() --- --- Namespaces are used for buffer highlights and virtual text, see ---- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`. +--- `nvim_buf_set_extmark()`. --- --- Namespaces can be named or anonymous. If `name` matches an existing --- namespace, the associated id is returned. If `name` is an empty string -- cgit From 4cced601c8cdfd6253266b035667dd0383a07ebe Mon Sep 17 00:00:00 2001 From: bfredl Date: Fri, 17 Jan 2025 13:44:07 +0100 Subject: feat(extmark): stack multiple highlight groups in `hl_group` This has been possible in the "backend" for a while but API was missing. Followup: we will need a `details2=true` mode for `nvim_get_hl_id_by_name` to return information in a way forward compatible with even further enhancements. --- runtime/lua/vim/_meta/api.lua | 3 +++ 1 file changed, 3 insertions(+) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 670e867c1e..3ffbc89b08 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -595,6 +595,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- - hl_group : highlight group used for the text range. This and below --- highlight groups can be supplied either as a string or as an integer, --- the latter of which can be obtained using `nvim_get_hl_id_by_name()`. +--- +--- Multiple highlight groups can be stacked by passing an array (highest +--- priority last). --- - hl_eol : when true, for a multiline highlight covering the --- EOL of a line, continue the highlight for the rest --- of the screen line (just like for diff and -- cgit From 34d808b73cbcb0a43636d826282193ab1ca8c148 Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Thu, 16 Jan 2025 18:10:22 +0100 Subject: feat(api): combined highlights in nvim_eval_statusline() Problem: Combined highlighting was not applied to nvim_eval_statusline(), and 'statuscolumn' sign segment/numhl highlights. Solution: Add an additional `groups` element to the return value of `nvim_eval_statusline()->highlights`. This is an array of stacked highlight groups (highest priority last). Also resolve combined highlights for the 'statuscolumn' sign segment/numhl highlights. Expose/synchronize some drawline.c logic that is now mimicked in three different places. --- runtime/lua/vim/_meta/api.lua | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 2f9ab5b846..6d9a17ea2b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1131,7 +1131,9 @@ function vim.api.nvim_eval(expr) end --- the "highlights" key in {opts} is true. Each element of the array is a --- |Dict| with these keys: --- - start: (number) Byte index (0-based) of first character that uses the highlight. ---- - group: (string) Name of highlight group. +--- - group: (string) Name of highlight group. May be removed in the future, use +--- `groups` instead. +--- - groups: (array) Names of stacked highlight groups (highest priority last). function vim.api.nvim_eval_statusline(str, opts) end --- @deprecated -- cgit From 931ee5591fa764a769946318e05062098baf7c21 Mon Sep 17 00:00:00 2001 From: georgev93 <39860568+georgev93@users.noreply.github.com> Date: Fri, 24 Jan 2025 22:57:45 -0500 Subject: feat(extmarks): virtual text can be right-aligned, truncated #31921 Problem: Right aligned virtual text can cover up buffer text if virtual text is too long Solution: An additional option for `virt_text_pos` called `eol_right_align` has been added to truncate virtual text if it would have otherwise covered up buffer text. This ensures the virtual text extends no further left than EOL. --- runtime/lua/vim/_meta/api.lua | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 6d9a17ea2b..50fb7e4f9d 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -589,6 +589,15 @@ function vim.api.nvim_buf_line_count(buffer) end --- (highest priority last). --- - virt_text_pos : position of virtual text. Possible values: --- - "eol": right after eol character (default). +--- - "eol_right_align": display right aligned in the window +--- unless the virtual text is longer than +--- the space available. If the virtual +--- text is too long, it is truncated to +--- fit in the window after the EOL +--- character. If the line is wrapped, the +--- virtual text is shown after the end of +--- the line rather than the previous +--- screen line. --- - "overlay": display over the specified column, without --- shifting the underlying text. --- - "right_align": display right aligned in the window. -- cgit From d84a95da7e11555376a0ce60a0d4b5fbe15892d3 Mon Sep 17 00:00:00 2001 From: glepnir Date: Mon, 27 Jan 2025 07:28:33 +0800 Subject: feat(api): nvim_get_autocmds filter by id#31549 Problem: nvim_get_autocmds cannot filter by id. Solution: Support it. --- runtime/lua/vim/_meta/api.lua | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 50fb7e4f9d..c7d5db60b1 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1246,27 +1246,28 @@ function vim.api.nvim_get_all_options_info() end --- match any combination of them. --- --- @param opts vim.api.keyset.get_autocmds Dict with at least one of the following: ---- - group (string|integer): the autocommand group name or id to match against. ---- - event (string|array): event or events to match against `autocmd-events`. ---- - pattern (string|array): pattern or patterns to match against `autocmd-pattern`. ---- Cannot be used with {buffer} ---- - buffer: Buffer number or list of buffer numbers for buffer local autocommands +--- - buffer: (integer) Buffer number or list of buffer numbers for buffer local autocommands --- `autocmd-buflocal`. Cannot be used with {pattern} +--- - event: (string|table) 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: ---- - id (number): the autocommand id (only when defined with the API). ---- - group (integer): the autocommand group id. ---- - group_name (string): the autocommand group name. ---- - desc (string): the autocommand description. ---- - event (string): the autocommand event. ---- - 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 +--- - 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. ---- - once (boolean): whether the autocommand is only run once. ---- - pattern (string): the autocommand pattern. +--- - desc: (string) the autocommand description. +--- - event: (string) 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|: ---- - buflocal (boolean): true if the autocommand is buffer local. ---- - buffer (number): the buffer number. function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. -- cgit From 6aa42e8f92bd8bea49b7b2accfe4ab67a5344e41 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 24 Jan 2025 13:01:25 +0000 Subject: fix: resolve all remaining LuaLS diagnostics --- runtime/lua/vim/_meta/api.lua | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'runtime/lua/vim/_meta/api.lua') diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index c7d5db60b1..3d10729d23 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -3,6 +3,10 @@ -- DO NOT EDIT error('Cannot require a meta file') +--- This file embeds vimdoc as the function descriptions +--- so ignore any doc related errors. +--- @diagnostic disable: undefined-doc-name,luadoc-miss-symbol + vim.api = {} --- @private -- cgit