From 0b74ad0a641f28d9d3da5353e98372d87078bd9d Mon Sep 17 00:00:00 2001 From: Riccardo Mazzarini Date: Tue, 5 Dec 2023 12:33:57 +0100 Subject: refactor(api): complete conversion from `Dictionary` to `Dict(opts)` (#26365) --- runtime/lua/vim/_meta/api.lua | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 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 49269ba631..4ad0a2e791 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -151,7 +151,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- `nvim_buf_lines_event`. Else the first notification --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. ---- @param opts table Optional parameters. +--- @param opts vim.api.keyset.buf_attach Optional parameters. --- • on_lines: Lua callback invoked on change. Return `true` to detach. Args: --- • the string "lines" --- • buffer handle @@ -284,7 +284,7 @@ function vim.api.nvim_buf_del_var(buffer, name) end --- Deletes the buffer. See `:bwipeout` --- --- @param buffer integer Buffer handle, or 0 for current buffer ---- @param opts table Optional parameters. Keys: +--- @param opts vim.api.keyset.buf_delete Optional parameters. Keys: --- • force: Force deletion and ignore unsaved changes. --- • unload: Unloaded only, do not delete. See `:bunload` function vim.api.nvim_buf_delete(buffer, opts) end @@ -307,7 +307,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @param buffer integer Buffer handle, or 0 for current buffer --- @param ns_id integer Namespace id from `nvim_create_namespace()` --- @param id integer Extmark id ---- @param opts table Optional parameters. Keys: +--- @param opts vim.api.keyset.get_extmark Optional parameters. Keys: --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead --- of id, true if omitted @@ -440,7 +440,7 @@ function vim.api.nvim_buf_get_option(buffer, name) end --- @param start_col integer Starting column (byte offset) on first line --- @param end_row integer Last line index, inclusive --- @param end_col integer Ending column (byte offset) on last line, exclusive ---- @param opts table Optional parameters. Currently unused. +--- @param opts vim.api.keyset.empty Optional parameters. Currently unused. --- @return string[] function vim.api.nvim_buf_get_text(buffer, start_row, start_col, end_row, end_col, opts) end @@ -626,7 +626,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac --- @param name string Mark name --- @param line integer Line number --- @param col integer Column/row number ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return boolean function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end @@ -675,7 +675,7 @@ function vim.api.nvim_buf_set_var(buffer, name, value) end --- @param src_id integer --- @param line integer --- @param chunks any[] ---- @param opts table +--- @param opts vim.api.keyset.empty --- @return integer function vim.api.nvim_buf_set_virtual_text(buffer, src_id, line, chunks, opts) end @@ -1241,7 +1241,7 @@ function vim.api.nvim_get_keymap(mode) end --- Marks are (1,0)-indexed. `api-indexing` --- --- @param name string Mark name ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return any[] function vim.api.nvim_get_mark(name, opts) end @@ -1439,7 +1439,7 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- virtual terminal having the intended size. --- --- @param buffer integer the buffer to use (expected to be empty) ---- @param opts table Optional parameters. +--- @param opts vim.api.keyset.open_term Optional parameters. --- • on_input: Lua callback for input sent, i e keypresses in --- terminal mode. Note: keypresses are sent raw as they would --- be to the pty master end. For instance, a carriage return @@ -1602,7 +1602,7 @@ function vim.api.nvim_out_write(str) end --- Doesn't check the validity of command arguments. --- --- @param str string Command line string to parse. Cannot contain "\n". ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. --- @return table function vim.api.nvim_parse_cmd(str, opts) end @@ -1685,7 +1685,7 @@ function vim.api.nvim_replace_termcodes(str, from_part, do_lt, special) end --- inserted in the buffer. Ignored for `cmdline-completion`. --- @param finish boolean Finish the completion and dismiss the popup menu. Implies --- {insert}. ---- @param opts table Optional parameters. Reserved for future use. +--- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. function vim.api.nvim_select_popupmenu_item(item, insert, finish, opts) end --- Sets the current buffer. -- cgit From 619407eb548c7df56bc99b945338e9446f846fbb Mon Sep 17 00:00:00 2001 From: Raphael Date: Thu, 14 Dec 2023 16:08:00 +0800 Subject: feat(nvim_open_term): convert LF => CRLF (#26384) Problem: Unlike termopen(), nvim_open_term() PTYs do not carriage-return the cursor on newline ("\n") input. nvim --clean :let chan_id = nvim_open_term(1, {}) :call chansend(chan_id, ["here", "are", "some", "lines"]) Actual behavior: here are some lines Expected behaviour: here are some lines Solution: Add `force_crlf` option, and enable it by default. --- 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 4ad0a2e791..231e1c3404 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1446,6 +1446,8 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- is sent as a "\r", not as a "\n". `textlock` applies. It --- is possible to call `nvim_chan_send()` directly in the --- callback however. ["input", term, bufnr, data] +--- • force_crlf: (boolean, default true) Convert "\n" to +--- "\r\n". --- @return integer function vim.api.nvim_open_term(buffer, opts) end -- cgit From e38027ef69f75653ee953b16ebf4a8652a3fb748 Mon Sep 17 00:00:00 2001 From: mathew Date: Tue, 15 Aug 2023 18:47:14 +0800 Subject: feat(ui): completeopt support popup like vim --- runtime/lua/vim/_meta/api.lua | 10 ++++++++++ 1 file changed, 10 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 231e1c3404..c8afbd58dd 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -773,6 +773,16 @@ function vim.api.nvim_command(command) end --- @return string function vim.api.nvim_command_output(command) end +--- Set info for the completion candidate index. if the info was shown in a +--- window, then the window and buffer ids are returned for further +--- customization. If the text was not shown, an empty dict is returned. +--- +--- @param index integer the completion candidate index +--- @param opts vim.api.keyset.complete_set Optional parameters. +--- • info: (string) info text. +--- @return table +function vim.api.nvim_complete_set(index, opts) end + --- Create or get an autocommand group `autocmd-groups`. --- To get an existing group id, do: --- -- cgit From 428edcde7068ab44040e19b43343741e5ca59770 Mon Sep 17 00:00:00 2001 From: Amanda Graven Date: Tue, 28 Nov 2023 21:05:33 +0100 Subject: feat(api): add forward and back mouse buttons --- 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 c8afbd58dd..c8c3e1c3af 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1375,7 +1375,7 @@ function vim.api.nvim_input(keys) end --- processed soon by the event loop. --- --- @param button string Mouse button: one of "left", "right", "middle", "wheel", ---- "move". +--- "move", "x1", "x2". --- @param action string For ordinary buttons, one of "press", "drag", "release". --- For the wheel, one of "up", "down", "left", "right". --- Ignored for "move". -- cgit From bbd5c6363c25e8fbbfb962f8f6c5ea1800d431ca Mon Sep 17 00:00:00 2001 From: luukvbaal Date: Tue, 26 Dec 2023 00:16:03 +0100 Subject: feat(extmarks): add virt_text_repeat_linebreak flag (#26625) Problem: Unable to predict which byte-offset to place virtual text to make it repeat visually in the wrapped part of a line. Solution: Add a flag to nvim_buf_set_extmark() that causes virtual text to repeat in wrapped lines. --- 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 c8c3e1c3af..ba18a16488 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -519,6 +519,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- text is selected or hidden because of scrolling with --- 'nowrap' or 'smoothscroll'. Currently only affects --- "overlay" virt_text. +--- • virt_text_repeat_linebreak : repeat the virtual text on +--- wrapped lines. --- • hl_mode : control how highlights are combined with the --- highlights of the text. Currently only affects virt_text --- highlights, but might affect `hl_group` in later versions. -- cgit From 714b075197c02d27d5c05133759ae97bed279b50 Mon Sep 17 00:00:00 2001 From: dundargoc <33953936+dundargoc@users.noreply.github.com> Date: Thu, 28 Dec 2023 03:28:48 +0100 Subject: docs: small fixes (#26651) Co-authored-by: Gregory Anders Co-authored-by: WillLillis --- runtime/lua/vim/_meta/api.lua | 1 - 1 file changed, 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 ba18a16488..d94cef481e 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1493,7 +1493,6 @@ function vim.api.nvim_open_term(buffer, opts) end --- ```lua --- vim.api.nvim_open_win(0, false, --- {relative='win', width=12, height=3, bufpos={100,10}}) ---- }) --- ``` --- --- @param buffer integer Buffer to display, or 0 for current buffer -- cgit From 3faace199583f3a36470b717ce3e386e476f3a30 Mon Sep 17 00:00:00 2001 From: Jaehwang Jung Date: Thu, 7 Dec 2023 21:01:50 +0900 Subject: docs: clarify on_bytes arguments based on extmark_splice doc --- runtime/lua/vim/_meta/api.lua | 12 ++++++++---- 1 file changed, 8 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 d94cef481e..c0dfa7635b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -173,11 +173,15 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- • start column of the changed text --- • byte offset of the changed text (from the start of --- the buffer) ---- • old end row of the changed text ---- • old end column of the changed text +--- • old end row of the changed text (offset from start +--- row) +--- • old end column of the changed text (if old end row +--- = 0, offset from start column) --- • old end byte length of the changed text ---- • new end row of the changed text ---- • new end column of the changed text +--- • new end row of the changed text (offset from start +--- row) +--- • new end column of the changed text (if new end row +--- = 0, offset from start column) --- • new end byte length of the changed text --- --- • on_changedtick: Lua callback invoked on changedtick -- cgit From 4e9298ecdf945b4d16c2c6e6e4ed82b97880917c Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 28 Dec 2023 17:50:05 -0500 Subject: refactor(gen_vimdoc): generate function doc from metadata, not from xml Problem: For function definitions to be included in the vimdoc (formatted) and to be exported as mpack data (unformatted), we had two internal representations of the same function/API metadata in duplicate; one is FunctionDoc (which was previously a dict), and the other is doxygen XML DOM from which vimdoc (functions sections) was generated. Solution: We should have a single path and unified data representation (i.e. FunctionDoc) that contains all the metadata and information about function APIs, from which both of mpack export and vimdoc are generated. I.e., vimdocs are no longer generated directly from doxygen XML nodes, but generated via: (XML DOM Nodes) ------------> FunctionDoc ------> mpack (unformatted) Recursive Internal | Formatting Metadata +---> vimdoc (formatted) This refactoring eliminates the hacky and ugly use of `fmt_vimhelp` in `fmt_node_as_vimhelp()` and all other helper functions! This way, `fmt_node_as_vimhelp()` can simplified as it no longer needs to handle generating of function docs, which needs to be done only in the topmost level of recursion. --- 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 c0dfa7635b..b6ce3fce8a 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -73,6 +73,9 @@ function vim.api.nvim__id_dictionary(dct) end function vim.api.nvim__id_float(flt) end --- @private +--- NB: if your UI doesn't use hlstate, this will not return hlstate first +--- time. +--- --- @param grid integer --- @param row integer --- @param col integer -- cgit From dc48a98f9ac614dc94739637c967aa29e064807e Mon Sep 17 00:00:00 2001 From: Jaehwang Jung Date: Mon, 25 Dec 2023 02:31:47 +0900 Subject: fix(decorations): validate botline for on_win Problem: Many decoration providers (treesitter injection highlighting, semantic token highlighting, inlay hint) rely on the correctness of the `botline` argument of `on_win` callback. However, `botline` can be smaller than the actual line number of the last displayed line if some lines are folded. In such cases, some decorations will be missing in the lines not covered by `botline`. Solution: Validate `botline` when invoking `on_win`. NOTE: It seems that the old code was deliberately avoiding this presumably due to performance reasons. However, I haven't experienced noticeable lag after this change, and I believe the cost of botline computation would be much smaller than the cost of decoration providers. --- runtime/lua/vim/_meta/api.lua | 4 +--- 1 file changed, 1 insertion(+), 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 c0dfa7635b..02128b66b9 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1761,9 +1761,7 @@ function vim.api.nvim_set_current_win(window) end --- • on_buf: called for each buffer being redrawn (before window --- callbacks) ["buf", bufnr, tick] --- • on_win: called when starting to redraw a specific window. ---- botline_guess is an approximation that does not exceed the ---- last line number. ["win", winid, bufnr, topline, ---- botline_guess] +--- ["win", winid, bufnr, topline, botline] --- • on_line: called for each buffer line being redrawn. (The --- interaction with fold lines is subject to change) ["win", --- winid, bufnr, row] -- cgit From f40df63bdca33d343cada6ceaafbc8b765ed7cc6 Mon Sep 17 00:00:00 2001 From: Jongwook Choi Date: Thu, 4 Jan 2024 11:09:13 -0500 Subject: fix(docs): make lines not overflow in vim docs Problem: Some lines in the generated vim doc are overflowing, not correctly wrapped at 78 characters. This happens when docs body contains several consecutive 'inline' elements generated by doxygen. Solution: Take into account the current column offset of the last line, and prepend some padding before doc_wrap(). --- runtime/lua/vim/_meta/api.lua | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 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 e85f81f5f9..19039eb226 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -155,7 +155,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return `true` to detach. Args: +--- • on_lines: Lua callback invoked on change. Return `true` to +--- detach. Args: --- • the string "lines" --- • buffer handle --- • b:changedtick @@ -168,7 +169,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- --- • on_bytes: Lua callback invoked on change. This --- callback receives more granular information about the ---- change compared to on_lines. Return `true` to detach. Args: +--- change compared to on_lines. Return `true` to +--- detach. Args: --- • the string "bytes" --- • buffer handle --- • b:changedtick @@ -530,7 +532,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- wrapped lines. --- • hl_mode : control how highlights are combined with the --- highlights of the text. Currently only affects virt_text ---- highlights, but might affect `hl_group` in later versions. +--- highlights, but might affect `hl_group` in +--- later versions. --- • "replace": only show the virt_text color. This is the --- default. --- • "combine": combine with background text color. @@ -740,7 +743,8 @@ function vim.api.nvim_chan_send(chan, data) end --- • 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. +--- • NOTE: If not passed, will only delete autocmds not in any +--- group. function vim.api.nvim_clear_autocmds(opts) end --- Executes an Ex command. @@ -808,7 +812,9 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua function or Vimscript function name string) or `command` (Ex command string). +--- Creates an `autocommand` event handler, defined by `callback` (Lua +--- function or Vimscript function name string) or `command` (Ex command +--- string). --- Example using Lua callback: --- --- ```lua @@ -1525,8 +1531,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • height: Window height (in character cells). Minimum of 1. --- • bufpos: Places float relative to buffer text (only when --- relative="win"). Takes a tuple of zero-indexed [line, ---- column]. `row` and `col` if given are applied relative to this position, else they ---- default to: +--- column]. `row` and `col` if given are +--- applied relative to this position, else they default to: --- • `row=1` and `col=0` if `anchor` is "NW" or "NE" --- • `row=0` and `col=0` if `anchor` is "SW" or "SE" (thus --- like a tooltip near the buffer text). @@ -1541,8 +1547,9 @@ function vim.api.nvim_open_term(buffer, opts) end --- • external: GUI should display the window as an external --- top-level window. Currently accepts no other positioning --- configuration together with this. ---- • zindex: Stacking order. floats with higher `zindex` go on top on floats with lower indices. Must be larger ---- than zero. The following screen elements have hard-coded +--- • zindex: Stacking order. floats with higher `zindex` go on +--- top on floats with lower indices. Must be larger than +--- zero. The following screen elements have hard-coded --- z-indices: --- • 100: insert completion popupmenu --- • 200: message scrollback @@ -1661,7 +1668,8 @@ function vim.api.nvim_parse_expression(expr, flags, highlight) end --- @param data string Multiline input. May be binary (containing NUL bytes). --- @param crlf boolean Also break lines at CR and CRLF. --- @param phase integer -1: paste in a single call (i.e. without streaming). To ---- "stream" a paste, call `nvim_paste` sequentially with these `phase` values: +--- "stream" a paste, call `nvim_paste` sequentially +--- with these `phase` values: --- • 1: starts the paste (exactly once) --- • 2: continues the paste (zero or more times) --- • 3: ends the paste (exactly once) -- cgit From 2f9ee9b6cfc61a0504fc0bc22bdf481828e2ea91 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Tue, 9 Jan 2024 17:36:46 +0000 Subject: fix(doc): improve doc generation of types using lpeg Added a lpeg grammar for LuaCATS and use it in lua2dox.lua --- runtime/lua/vim/_meta/api.lua | 5 ++--- 1 file changed, 2 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 19039eb226..3f06d4fd43 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -812,9 +812,8 @@ function vim.api.nvim_complete_set(index, opts) end --- @return integer function vim.api.nvim_create_augroup(name, opts) end ---- Creates an `autocommand` event handler, defined by `callback` (Lua ---- function or Vimscript function name string) or `command` (Ex command ---- string). +--- Creates an `autocommand` event handler, defined by `callback` (Lua function +--- or Vimscript function name string) or `command` (Ex command string). --- Example using Lua callback: --- --- ```lua -- cgit From 2645c9d576e430e62b60d1902d4a6b887e46a670 Mon Sep 17 00:00:00 2001 From: Luuk van Baal Date: Wed, 17 Jan 2024 15:55:00 +0100 Subject: docs(extmarks): add undocumented "details" array fields --- runtime/lua/vim/_meta/api.lua | 11 ++++++++--- 1 file changed, 8 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 3f06d4fd43..f773ddd75c 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -323,8 +323,8 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- @return integer[] function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end ---- Gets `extmarks` (including `signs`) in "traversal order" from a `charwise` ---- region defined by buffer positions (inclusive, 0-indexed `api-indexing`). +--- Gets `extmarks` in "traversal order" from a `charwise` region defined by +--- buffer positions (inclusive, 0-indexed `api-indexing`). --- Region can be given as (row,col) tuples, or valid extmark ids (whose --- positions define the bounds). 0 and -1 are understood as (0,0) and (-1,-1) --- respectively, thus the following are equivalent: @@ -339,6 +339,9 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Note: when using extmark ranges (marks with a end_row/end_col position) --- the `overlap` option might be useful. Otherwise only the start position of --- an extmark will be considered. +--- Note: legacy signs placed through the `:sign` commands are implemented as +--- extmarks and will show up here. Their details array will contain a +--- `sign_name` field. --- Example: --- --- ```lua @@ -567,7 +570,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- text around the mark was deleted and then restored by --- undo. Defaults to true. --- • invalidate : boolean that indicates whether to hide the ---- extmark if the entirety of its range is deleted. If +--- extmark if the entirety of its range is deleted. For +--- hidden marks, an "invalid" key is added to the "details" +--- array of `nvim_buf_get_extmarks()` and family. If --- "undo_restore" is false, the extmark is deleted instead. --- • priority: a priority value for the highlight group or sign --- attribute. For example treesitter highlighting uses a -- cgit From 6ea6b3fee27d51607ca4a5ace46dbc38a4481bcb Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Wed, 24 Jan 2024 16:36:25 -0600 Subject: feat(ui): add support for OSC 8 hyperlinks (#27109) Extmarks can contain URLs which can then be drawn in any supporting UI. In the TUI, for example, URLs are "drawn" by emitting the OSC 8 control sequence to the TTY. On terminals which support the OSC 8 sequence this will create clickable hyperlinks. URLs are treated as inline highlights in the decoration subsystem, so are included in the `DecorSignHighlight` structure. However, unlike other inline highlights they use allocated memory which must be freed, so they set the `ext` flag in `DecorInline` so that their lifetimes are managed along with other allocated memory like virtual text. The decoration subsystem then adds the URLs as a new highlight attribute. The highlight subsystem maintains a set of unique URLs to avoid duplicating allocations for the same string. To attach a URL to an existing highlight attribute we call `hl_add_url` which finds the URL in the set (allocating and adding it if it does not exist) and sets the `url` highlight attribute to the index of the URL in the set (using an index helps keep the size of the `HlAttrs` struct small). This has the potential to lead to an increase in highlight attributes if a URL is used over a range that contains many different highlight attributes, because now each existing attribute must be combined with the URL. In practice, however, URLs typically span a range containing a single highlight (e.g. link text in Markdown), so this is likely just a pathological edge case. When a new highlight attribute is defined with a URL it is copied to all attached UIs with the `hl_attr_define` UI event. The TUI manages its own set of URLs (just like the highlight subsystem) to minimize allocations. The TUI keeps track of which URL is "active" for the cell it is printing. If no URL is active and a cell containing a URL is printed, the opening OSC 8 sequence is emitted and that URL becomes the actively tracked URL. If the cursor is moved while in the middle of a URL span, we emit the terminating OSC sequence to prevent the hyperlink from spanning multiple lines. This does not support nested hyperlinks, but that is a rare (and, frankly, bizarre) use case. If a valid use case for nested hyperlinks ever presents itself we can address that issue then. --- 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 f773ddd75c..076aae7dbe 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -607,6 +607,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- drawn by a UI. When set, the UI will receive win_extmark --- events. Note: the mark is positioned by virt_text --- attributes. Can be used together with virt_text. +--- • url: A URL to associate with this extmark. In the TUI, the +--- OSC 8 control sequence is used to generate a clickable +--- hyperlink to this URL. --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end -- cgit From 28d1640dd6043f25cd3ae761dc9c4c8d374a8ce1 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Fri, 26 Jan 2024 11:38:19 +0000 Subject: feat: improve return type annotations for vim.api.* --- runtime/lua/vim/_meta/api.lua | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 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 076aae7dbe..f9fa364158 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -320,7 +320,7 @@ function vim.api.nvim_buf_get_commands(buffer, opts) end --- • details: Whether to include the details dict --- • hl_name: Whether to include highlight group name instead --- of id, true if omitted ---- @return integer[] +--- @return vim.api.keyset.get_extmark_item function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- Gets `extmarks` in "traversal order" from a `charwise` region defined by @@ -376,14 +376,14 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end --- if their start position is less than `start` --- • type: Filter marks by type: "highlight", "sign", --- "virt_text" and "virt_lines" ---- @return any[] +--- @return vim.api.keyset.get_extmark_item[] function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- Gets a list of buffer-local `mapping` definitions. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return table[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_buf_get_keymap(buffer, mode) end --- Gets a line-range from the buffer. @@ -1153,7 +1153,7 @@ function vim.api.nvim_get_all_options_info() end --- • buffer: Buffer number or list of buffer numbers for buffer --- local autocommands `autocmd-buflocal`. Cannot be used with --- {pattern} ---- @return any[] +--- @return vim.api.keyset.get_autocmds.ret[] function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. @@ -1179,7 +1179,7 @@ function vim.api.nvim_get_color_by_name(name) end --- Keys are color names (e.g. "Aqua") and values are 24-bit RGB color values --- (e.g. 65535). --- ---- @return table +--- @return table function vim.api.nvim_get_color_map() end --- Gets a map of global (non-buffer-local) Ex commands. @@ -1229,7 +1229,7 @@ function vim.api.nvim_get_current_win() end --- instead of effective definition `:hi-link`. --- • create: (boolean, default true) When highlight group --- doesn't exist create it. ---- @return table +--- @return vim.api.keyset.hl_info function vim.api.nvim_get_hl(ns_id, opts) end --- @deprecated @@ -1264,7 +1264,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 table[] +--- @return vim.api.keyset.keymap[] function vim.api.nvim_get_keymap(mode) end --- Returns a `(row, col, buffer, buffername)` tuple representing the position @@ -1274,18 +1274,18 @@ function vim.api.nvim_get_keymap(mode) end --- --- @param name string Mark name --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return any[] +--- @return vim.api.keyset.get_mark function vim.api.nvim_get_mark(name, opts) end --- Gets the current mode. `mode()` "blocking" is true if Nvim is waiting for --- input. --- ---- @return table +--- @return vim.api.keyset.get_mode function vim.api.nvim_get_mode() end --- Gets existing, non-anonymous `namespace`s. --- ---- @return table +--- @return table function vim.api.nvim_get_namespaces() end --- @deprecated @@ -1295,7 +1295,7 @@ function vim.api.nvim_get_option(name) end --- @deprecated --- @param name string ---- @return table +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info(name) end --- Gets the option information for one option from arbitrary buffer or window @@ -1325,7 +1325,7 @@ function vim.api.nvim_get_option_info(name) end --- • win: `window-ID`. Used for getting window local options. --- • buf: Buffer number. Used for getting buffer local options. --- Implies {scope} is "local". ---- @return table +--- @return vim.api.keyset.get_option_info function vim.api.nvim_get_option_info2(name, opts) end --- Gets the value of an option. The behavior of this function matches that of @@ -1637,7 +1637,7 @@ function vim.api.nvim_out_write(str) end --- --- @param str string Command line string to parse. Cannot contain "\n". --- @param opts vim.api.keyset.empty Optional parameters. Reserved for future use. ---- @return table +--- @return vim.api.keyset.parse_cmd function vim.api.nvim_parse_cmd(str, opts) end --- Parse a Vimscript expression. @@ -1985,7 +1985,7 @@ function vim.api.nvim_win_get_buf(window) end --- `relative` is empty for normal windows. --- --- @param window integer Window handle, or 0 for current window ---- @return table +--- @return vim.api.keyset.float_config function vim.api.nvim_win_get_config(window) end --- Gets the (1,0)-indexed, buffer-relative cursor position for a given window -- cgit From ca9f6f56949d66f0f6467fa64b215f861fe0a3bf Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Sun, 28 Jan 2024 23:18:33 -0800 Subject: feat(api): add nvim_tabpage_set_win (#27222) Allows setting the current window of a non-current tabpage without switching tabpages. --- runtime/lua/vim/_meta/api.lua | 6 ++++++ 1 file changed, 6 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 f9fa364158..bedc218626 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1952,6 +1952,12 @@ function vim.api.nvim_tabpage_list_wins(tabpage) end --- @param value any Variable value function vim.api.nvim_tabpage_set_var(tabpage, name, value) end +--- Sets the current window in a tabpage +--- +--- @param tabpage integer Tabpage handle, or 0 for current tabpage +--- @param win integer Window handle, must already belong to {tabpage} +function vim.api.nvim_tabpage_set_win(tabpage, win) end + --- Calls a function with window as temporary current window. --- --- @param window integer Window handle, or 0 for current window -- cgit From 6bba4becedaea5a330c0c9d9427fb495e8092dac Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Wed, 31 Jan 2024 19:43:35 -0800 Subject: feat(api): make nvim_open_win support non-floating windows (#25550) Adds support to `nvim_open_win` and `nvim_win_set_config` for creating and manipulating split (non-floating) windows. --- runtime/lua/vim/_meta/api.lua | 39 ++++++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 9 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 bedc218626..77a29cb4c1 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1483,15 +1483,24 @@ function vim.api.nvim_notify(msg, log_level, opts) end --- @return integer function vim.api.nvim_open_term(buffer, opts) end ---- Open a new window. ---- Currently this is used to open floating and external windows. Floats are ---- windows that are drawn above the split layout, at some anchor position in ---- some other window. Floats can be drawn internally or by external GUI with ---- the `ui-multigrid` extension. External windows are only supported with ---- multigrid GUIs, and are displayed as separate top-level windows. +--- Opens a new split window, or a floating window if `relative` is specified, +--- or an external window (managed by the UI) if `external` is specified. +--- Floats are windows that are drawn above the split layout, at some anchor +--- position in some other window. Floats can be drawn internally or by +--- external GUI with the `ui-multigrid` extension. External windows are only +--- supported with multigrid GUIs, and are displayed as separate top-level +--- windows. --- For a general overview of floats, see `api-floatwin`. ---- Exactly one of `external` and `relative` must be specified. The `width` ---- and `height` of the new window must be specified. +--- The `width` and `height` of the new window must be specified when opening +--- a floating window, but are optional for normal windows. +--- If `relative` and `external` are omitted, a normal "split" window is +--- created. The `win` property determines which window will be split. If no +--- `win` is provided or `win == 0`, a window will be created adjacent to the +--- current window. If -1 is provided, a top-level split will be created. +--- `vertical` and `split` are only valid for normal windows, and are used to +--- control split direction. For `vertical`, the exact direction is determined +--- by `'splitright'` and `'splitbelow'`. Split windows cannot have +--- `bufpos`/`row`/`col`/`border`/`title`/`footer` properties. --- With relative=editor (row=0,col=0) refers to the top-left corner of the --- screen-grid and (row=Lines-1,col=Columns-1) refers to the bottom-right --- corner. Fractional values are allowed, but the builtin implementation @@ -1515,6 +1524,15 @@ function vim.api.nvim_open_term(buffer, opts) end --- {relative='win', width=12, height=3, bufpos={100,10}}) --- ``` --- +--- Example (Lua): vertical split left of the current window +--- +--- ```lua +--- vim.api.nvim_open_win(0, false, { +--- split = 'left', +--- win = 0 +--- }) +--- ``` +--- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) --- @param config vim.api.keyset.float_config Map defining the window configuration. Keys: @@ -1526,7 +1544,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • "cursor" Cursor position in current window. --- • "mouse" Mouse position --- ---- • win: `window-ID` for relative="win". +--- • 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): --- • "NW" northwest (default) @@ -1623,6 +1642,8 @@ function vim.api.nvim_open_term(buffer, opts) end --- • fixed: If true when anchor is NW or SW, the float window --- would be kept fixed even if the window would be truncated. --- • hide: If true the floating window will be hidden. +--- • vertical: Split vertically `:vertical`. +--- • split: Split direction: "left", "right", "above", "below". --- @return integer function vim.api.nvim_open_win(buffer, enter, config) end -- cgit From b162adbb7ca4f980e938a4a06a49218a9ed496cf Mon Sep 17 00:00:00 2001 From: nikolightsaber <103886134+nikolightsaber@users.noreply.github.com> Date: Thu, 8 Feb 2024 11:59:31 +0100 Subject: feat(api): pass 0 to nvim_get_chan_info for current channel (#27321) Getting current channel info was kind of annoying via RPC. Two functions had to be called: 1. `nvim_get_api_info` which returns `[channel_id, meta_data]`. - This results in `channel_id = api.nvim_get_api_info()[0]`. - Here the meta_data is sent but never used. 2. Finally call `nvim_get_chan_info(channel_id)`. This commit reduces the need for `nvim_get_api_info` as passing 0 returns current channel info. --- 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 77a29cb4c1..8b29727196 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1158,7 +1158,7 @@ function vim.api.nvim_get_autocmds(opts) end --- Gets information about a channel. --- ---- @param chan integer +--- @param chan integer channel_id, or 0 for current channel --- @return table function vim.api.nvim_get_chan_info(chan) end -- cgit From 44ec4b5b18d1ba856dc3305d8dfb0e8d9507dd50 Mon Sep 17 00:00:00 2001 From: Will Hopkins Date: Fri, 9 Feb 2024 08:17:10 -0800 Subject: refactor: rename FloatConfig to WinConfig #27397 `FloatConfig` is no longer used only for floats, so the name is counterintuitive. Followup to #25550 --- 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 8b29727196..f46ab8023f 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1535,7 +1535,7 @@ function vim.api.nvim_open_term(buffer, opts) end --- --- @param buffer integer Buffer to display, or 0 for current buffer --- @param enter boolean Enter the window (make it the current window) ---- @param config vim.api.keyset.float_config Map defining the window configuration. Keys: +--- @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 @@ -2093,7 +2093,7 @@ function vim.api.nvim_win_set_buf(window, buffer) end --- changed. `row`/`col` and `relative` must be reconfigured together. --- --- @param window integer Window handle, or 0 for current window ---- @param config vim.api.keyset.float_config Map defining the window configuration, see `nvim_open_win()` +--- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()` function vim.api.nvim_win_set_config(window, config) end --- Sets the (1,0)-indexed cursor position in the window. `api-indexing` This -- cgit From 55a4aa41bb27aa9439fea11c4ebcfec2ee87844d Mon Sep 17 00:00:00 2001 From: Gregory Anders <8965202+gpanders@users.noreply.github.com> Date: Thu, 15 Feb 2024 19:56:58 -0600 Subject: docs: document breaking change for nvim_create_autocmd callback (#27484) https://github.com/neovim/neovim/pull/27428 changed the semantics of callbacks passed to nvim_create_autocmd such that any truthy value will delete the autocommand (rather than just the literal boolean value `true`). Update the documentation accordingly and add an entry to `news.txt`. The behavior is now consistent between nvim_create_autocmd and nvim_buf_attach. --- runtime/lua/vim/_meta/api.lua | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 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 f46ab8023f..0978f0acf5 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -155,8 +155,9 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return `true` to ---- detach. Args: +--- • on_lines: Lua callback invoked on change. Return a +--- truthy value (not `false` or `nil`) +--- to detach. Args: --- • the string "lines" --- • buffer handle --- • b:changedtick @@ -169,7 +170,8 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- --- • on_bytes: Lua callback invoked on change. This --- callback receives more granular information about the ---- change compared to on_lines. Return `true` to +--- change compared to on_lines. Return a truthy value +--- (not `false` or `nil`) to --- detach. Args: --- • the string "bytes" --- • buffer handle @@ -863,9 +865,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- troubleshooting). --- • callback (function|string) optional: Lua function (or --- Vimscript function name, if string) called when the ---- event(s) is triggered. Lua callback can return true to ---- delete the autocommand, and receives a table argument with ---- these keys: +--- event(s) is triggered. Lua callback can return a truthy +--- value (not `false` or `nil`) to delete the +--- autocommand. Receives a table argument with these keys: --- • id: (number) autocommand id --- • event: (string) name of the triggered event --- `autocmd-events` -- cgit From a0790558c3097f2813c56e404af30c3e2d8b8983 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Tue, 20 Feb 2024 19:53:49 +0800 Subject: fix(extmarks): priority order of inline and non-inline virt_text (#27532) --- runtime/lua/vim/_meta/api.lua | 7 ++++--- 1 file changed, 4 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 0978f0acf5..31ef3dd64b 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -576,9 +576,10 @@ function vim.api.nvim_buf_line_count(buffer) end --- hidden marks, an "invalid" key is added to the "details" --- array of `nvim_buf_get_extmarks()` and family. If --- "undo_restore" is false, the extmark is deleted instead. ---- • priority: a priority value for the highlight group or sign ---- attribute. For example treesitter highlighting uses a ---- value of 100. +--- • priority: a priority value for the highlight group, sign +--- attribute or virtual text. For virtual text, item with +--- highest priority is drawn last. For example treesitter +--- highlighting uses a value of 100. --- • strict: boolean that indicates extmark should not be --- placed if the line or column value is past the end of the --- buffer or end of the line respectively. Defaults to true. -- cgit From 6d8bbfe19df2175637a1e47ac1aafb0e96e35b38 Mon Sep 17 00:00:00 2001 From: rktjmp Date: Thu, 22 Feb 2024 00:25:08 +1100 Subject: docs: remove mention of foreground/background/special keys in nvim_set_hl (#27558) To align the output of `nvim_get_hl` with its documentation -- which points to `nvim_set_hl`, remove mentions of the keys `foreground`, `background` and `special`. The long keys are are still supported (via fallback checks inside `dict2hlattrs`), but the `fg`, `bg` and `sp` keys are preferenced. --- 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 31ef3dd64b..cfdb65c2b5 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -1819,9 +1819,9 @@ function vim.api.nvim_set_decoration_provider(ns_id, opts) end --- activate them. --- @param name string Highlight group name, e.g. "ErrorMsg" --- @param val vim.api.keyset.highlight Highlight definition map, accepts the following keys: ---- • fg (or foreground): color name or "#RRGGBB", see note. ---- • bg (or background): color name or "#RRGGBB", see note. ---- • sp (or special): color name or "#RRGGBB" +--- • fg: color name or "#RRGGBB", see note. +--- • bg: color name or "#RRGGBB", see note. +--- • sp: color name or "#RRGGBB" --- • blend: integer between 0 and 100 --- • bold: boolean --- • standout: boolean -- cgit From 1c032ad703a19cd5c8498ee95f9352df87a91139 Mon Sep 17 00:00:00 2001 From: altermo <107814000+altermo@users.noreply.github.com> Date: Tue, 6 Feb 2024 11:52:42 +0100 Subject: feat(extmark): window scoped extmark Co-authored-by: zeertzjq --- runtime/lua/vim/_meta/api.lua | 22 ++++++++++++++++++++++ 1 file changed, 22 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 cfdb65c2b5..998608ae16 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -613,6 +613,8 @@ function vim.api.nvim_buf_line_count(buffer) end --- • url: A URL to associate with this extmark. In the TUI, the --- OSC 8 control sequence is used to generate a clickable --- hyperlink to this URL. +--- • scoped: boolean that indicates that the extmark should +--- only be displayed in the namespace scope. (experimental) --- @return integer function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end @@ -1982,6 +1984,13 @@ function vim.api.nvim_tabpage_set_var(tabpage, name, value) end --- @param win integer Window handle, must already belong to {tabpage} function vim.api.nvim_tabpage_set_win(tabpage, win) end +--- Adds the namespace scope to the window. +--- +--- @param window integer Window handle, or 0 for current window +--- @param ns_id integer the namespace to add +--- @return boolean +function vim.api.nvim_win_add_ns(window, ns_id) end + --- Calls a function with window as temporary current window. --- --- @param window integer Window handle, or 0 for current window @@ -2032,6 +2041,12 @@ function vim.api.nvim_win_get_cursor(window) end --- @return integer function vim.api.nvim_win_get_height(window) end +--- Gets all the namespaces scopes associated with a window. +--- +--- @param window integer Window handle, or 0 for current window +--- @return integer[] +function vim.api.nvim_win_get_ns(window) end + --- Gets the window number --- --- @param window integer Window handle, or 0 for current window @@ -2084,6 +2099,13 @@ function vim.api.nvim_win_hide(window) end --- @return boolean function vim.api.nvim_win_is_valid(window) end +--- Removes the namespace scope from the window. +--- +--- @param window integer Window handle, or 0 for current window +--- @param ns_id integer the namespace to remove +--- @return boolean +function vim.api.nvim_win_remove_ns(window, ns_id) end + --- Sets the current buffer in a window, without side effects --- --- @param window integer Window handle, or 0 for current window -- cgit From c2ddef30e743d8c1de6d960bf230b8646cb49c7c Mon Sep 17 00:00:00 2001 From: Evgeni Chasnovski Date: Sun, 25 Feb 2024 02:45:34 +0200 Subject: docs: fix several misleading and superfluous wordings (#27609) --- runtime/lua/vim/_meta/api.lua | 19 +++++++------------ 1 file changed, 7 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 998608ae16..aee866f324 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -584,21 +584,16 @@ function vim.api.nvim_buf_line_count(buffer) end --- placed if the line or column value is past the end of the --- buffer or end of the line respectively. Defaults to true. --- • sign_text: string of length 1-2 used to display in the ---- sign column. Note: ranges are unsupported and decorations ---- are only applied to start_row +--- sign column. --- • sign_hl_group: name of the highlight group used to ---- highlight the sign column text. Note: ranges are ---- unsupported and decorations are only applied to start_row +--- highlight the sign column text. --- • number_hl_group: name of the highlight group used to ---- highlight the number column. Note: ranges are unsupported ---- and decorations are only applied to start_row +--- highlight the number column. --- • line_hl_group: name of the highlight group used to ---- highlight the whole line. Note: ranges are unsupported and ---- decorations are only applied to start_row +--- highlight the whole line. --- • cursorline_hl_group: name of the highlight group used to ---- highlight the line when the cursor is on the same line as ---- the mark and 'cursorline' is enabled. Note: ranges are ---- unsupported and decorations are only applied to start_row +--- highlight the sign column text when the cursor is on the +--- same line as the mark and 'cursorline' is enabled. --- • conceal: string which should be either empty or a single --- character. Enable concealing similar to `:syn-conceal`. --- When a character is supplied it is used as `:syn-cchar`. @@ -1807,7 +1802,7 @@ function vim.api.nvim_set_current_win(window) end --- • on_win: called when starting to redraw a specific window. --- ["win", winid, bufnr, topline, botline] --- • on_line: called for each buffer line being redrawn. (The ---- interaction with fold lines is subject to change) ["win", +--- interaction with fold lines is subject to change) ["line", --- winid, bufnr, row] --- • on_end: called at the end of a redraw cycle ["end", tick] function vim.api.nvim_set_decoration_provider(ns_id, opts) end -- cgit From 9beb40a4db5613601fc1a4b828a44e5977eca046 Mon Sep 17 00:00:00 2001 From: Lewis Russell Date: Thu, 15 Feb 2024 17:16:04 +0000 Subject: feat(docs): replace lua2dox.lua Problem: The documentation flow (`gen_vimdoc.py`) has several issues: - it's not very versatile - depends on doxygen - doesn't work well with Lua code as it requires an awkward filter script to convert it into pseudo-C. - The intermediate XML files and filters makes it too much like a rube goldberg machine. Solution: Re-implement the flow using Lua, LPEG and treesitter. - `gen_vimdoc.py` is now replaced with `gen_vimdoc.lua` and replicates a portion of the logic. - `lua2dox.lua` is gone! - No more XML files. - Doxygen is now longer used and instead we now use: - LPEG for comment parsing (see `scripts/luacats_grammar.lua` and `scripts/cdoc_grammar.lua`). - LPEG for C parsing (see `scripts/cdoc_parser.lua`) - Lua patterns for Lua parsing (see `scripts/luacats_parser.lua`). - Treesitter for Markdown parsing (see `scripts/text_utils.lua`). - The generated `runtime/doc/*.mpack` files have been removed. - `scripts/gen_eval_files.lua` now instead uses `scripts/cdoc_parser.lua` directly. - Text wrapping is implemented in `scripts/text_utils.lua` and appears to produce more consistent results (the main contributer to the diff of this change). --- runtime/lua/vim/_meta/api.lua | 843 ++++++++++++++++++++++++------------------ 1 file changed, 474 insertions(+), 369 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 aee866f324..d2f624fd97 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -38,6 +38,7 @@ function vim.api.nvim__get_runtime(pat, all, opts) end --- @private --- Returns object given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -47,6 +48,7 @@ function vim.api.nvim__id(obj) end --- @private --- Returns array given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -56,6 +58,7 @@ function vim.api.nvim__id_array(arr) end --- @private --- Returns dictionary given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -65,6 +68,7 @@ function vim.api.nvim__id_dictionary(dct) end --- @private --- Returns floating-point value given as argument. +--- --- This API function is used for testing. One should not rely on its presence --- in plugins. --- @@ -108,17 +112,20 @@ function vim.api.nvim__stats() end 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 @@ -131,11 +138,12 @@ function vim.api.nvim__unpack(str) end --- @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 +--- highlight to end of line --- @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. +--- --- Example (Lua): capture buffer updates in a global `events` variable (use --- "vim.print(events)" to see its contents): --- @@ -148,6 +156,7 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- }) --- ``` --- +--- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param send_buffer boolean True if the initial notification should contain the --- whole buffer: first notification will be @@ -155,77 +164,70 @@ function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start --- will be `nvim_buf_changedtick_event`. Not for Lua --- callbacks. --- @param opts vim.api.keyset.buf_attach Optional parameters. ---- • on_lines: Lua callback invoked on change. Return a ---- truthy value (not `false` or `nil`) ---- to detach. Args: ---- • the string "lines" ---- • buffer handle ---- • b:changedtick ---- • first line that changed (zero-indexed) ---- • last line that was changed ---- • last line in the updated range ---- • byte count of previous contents ---- • deleted_codepoints (if `utf_sizes` is true) ---- • deleted_codeunits (if `utf_sizes` is true) ---- ---- • on_bytes: Lua callback invoked on change. This ---- callback receives more granular information about the ---- change compared to on_lines. Return a truthy value ---- (not `false` or `nil`) to ---- detach. Args: ---- • the string "bytes" ---- • buffer handle ---- • b:changedtick ---- • start row of the changed text (zero-indexed) ---- • start column of the changed text ---- • byte offset of the changed text (from the start of ---- the buffer) ---- • old end row of the changed text (offset from start ---- row) ---- • old end column of the changed text (if old end row ---- = 0, offset from start column) ---- • old end byte length of the changed text ---- • new end row of the changed text (offset from start ---- row) ---- • new end column of the changed text (if new end row ---- = 0, offset from start column) ---- • new end byte length of the changed text ---- ---- • on_changedtick: Lua callback invoked on changedtick ---- increment without text change. Args: ---- • the string "changedtick" ---- • buffer handle ---- • b:changedtick ---- ---- • on_detach: Lua callback invoked on detach. Args: ---- • the string "detach" ---- • buffer handle ---- ---- • on_reload: Lua callback invoked on reload. The entire ---- buffer content should be considered changed. Args: ---- • the string "reload" ---- • buffer handle ---- ---- • utf_sizes: incl