Merge #28432 nvim_win_xx_ns are EXPERIMENTAL

This commit is contained in:
Justin M. Keyes 2024-05-12 15:07:10 -07:00 committed by GitHub
commit c7958356be
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
8 changed files with 171 additions and 101 deletions

View File

@ -2776,8 +2776,8 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
• 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)
• scoped: boolean (EXPERIMENTAL) enables "scoping" for the
extmark. See |nvim__win_add_ns()|
Return: ~
Id of the created/updated extmark
@ -2859,27 +2859,23 @@ nvim_set_decoration_provider({ns_id}, {opts})
["end", tick]
<
nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()*
Adds the namespace scope to the window.
nvim__win_add_ns({window}, {ns_id}) *nvim__win_add_ns()*
EXPERIMENTAL: this API will change in the future.
Scopes a namespace to the a window, so extmarks in the namespace will be
active only in the given window.
Parameters: ~
• {window} Window handle, or 0 for current window
• {ns_id} the namespace to add
• {ns_id} Namespace
Return: ~
true if the namespace was added, else false
nvim_win_get_ns({window}) *nvim_win_get_ns()*
Gets all the namespaces scopes associated with a window.
nvim__win_del_ns({window}, {ns_id}) *nvim__win_del_ns()*
EXPERIMENTAL: this API will change in the future.
Parameters: ~
• {window} Window handle, or 0 for current window
Return: ~
a list of namespaces ids
nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()*
Removes the namespace scope from the window.
Unscopes a namespace (un-binds it from the given scope).
Parameters: ~
• {window} Window handle, or 0 for current window
@ -2888,6 +2884,17 @@ nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()*
Return: ~
true if the namespace was removed, else false
nvim__win_get_ns({window}) *nvim__win_get_ns()*
EXPERIMENTAL: this API will change in the future.
Gets the namespace scopes for a given window.
Parameters: ~
• {window} Window handle, or 0 for current window
Return: ~
a list of namespaces ids
==============================================================================
Window Functions *api-window*

View File

@ -383,7 +383,7 @@ Use existing common {verb} names (actions) if possible:
- enable: Enables/disables functionality. Signature should be
`enable(enable?:boolean, filter?:table)`.
- eval: Evaluates an expression
- exec: Executes code
- exec: Executes code, may return a result
- fmt: Formats
- get: Gets things (often by a query)
- inspect: Presents a high-level, often interactive, view
@ -405,8 +405,8 @@ Do NOT use these deprecated verbs:
- show: Redundant with "print", "echo"
- toggle: Prefer `enable(not is_enabled())`.
Use consistent names for {noun} (nouns) in API functions: buffer is called
"buf" everywhere, not "buffer" in some places and "buf" in others.
Use consistent names for {topic} in API functions: buffer is called "buf"
everywhere, not "buffer" in some places and "buf" in others.
- buf: Buffer
- chan: |channel|
- cmd: Command
@ -419,10 +419,10 @@ Use consistent names for {noun} (nouns) in API functions: buffer is called
- win: Window
Do NOT use these deprecated nouns:
- buffer
- buffer Use "buf" instead
- callback Use on_foo instead
- command
- window
- command Use "cmd" instead
- window Use "win" instead
*dev-name-events*
Use the "on_" prefix to name event-handling callbacks and also the interface for
@ -440,12 +440,15 @@ Example: >
<
*dev-name-api*
Use this format to name new RPC |API| functions: >
nvim_{noun}_{verb}_{arbitrary-qualifiers}
nvim_{topic}_{verb}_{arbitrary-qualifiers}
If the function acts on an object then {noun} is the name of that object
(e.g. "buf" or "win"). If the function operates in a "global" context then
{noun} is usually omitted (but consider "namespacing" your global operations
with a {noun} that groups functions under a common concept).
Do not add new nvim_buf/nvim_win/nvim_tabpage APIs, unless you are certain the
concept will NEVER be applied to more than one "scope". That is, {topic}
should be the TOPIC ("ns", "extmark", "option", …) that acts on the scope(s)
(buf/win/tabpage/global), it should NOT be the scope. Instead the scope should
be a parameter (typically manifest as mutually-exclusive buf/win/… flags like
|nvim_get_option_value()|, or less commonly as a `scope: string` field like
|nvim_get_option_info2()|).
- Example: `nvim_get_keymap('v')` operates in a global context (first
parameter is not a Buffer). The "get" verb indicates that it gets anything
@ -455,6 +458,58 @@ with a {noun} that groups functions under a common concept).
and uses the "del" {verb}.
INTERFACE PATTERNS *dev-patterns*
Prefer adding a single `nvim_{topic}_{verb}_…` interface for a given topic.
Example: >
nvim_ns_add(
ns_id: int,
filter: {
handle: integer (buf/win/tabpage id)
scope: "global" | "win" | "buf" | "tabpage"
}
): { ok: boolean }
nvim_ns_get(
ns_id: int,
filter: {
handle: integer (buf/win/tabpage id)
scope: "global" | "win" | "buf" | "tabpage"
}
): { ids: int[] }
nvim_ns_del(
ns_id: int,
filter: {
handle: integer (buf/win/tabpage id)
scope: "global" | "win" | "buf" | "tabpage"
}
): { ok: boolean }
Anti-Example:
Creating separate `nvim_xx`, `nvim_buf_xx`, `nvim_win_xx`, and
`nvim_tabpage_xx`, functions all for the same `xx` topic, requires 4x the
amount of documentation, tests, boilerplate, and interfaces, which users must
comprehend, maintainers must maintain, etc. Thus the following is NOT
recommended (compare these 12(!) functions to the above 3 functions): >
nvim_add_ns(…)
nvim_buf_add_ns(…)
nvim_win_add_ns(…)
nvim_tabpage_add_ns(…)
nvim_del_ns(…)
nvim_buf_del_ns(…)
nvim_win_del_ns(…)
nvim_tabpage_del_ns(…)
nvim_get_ns(…)
nvim_buf_get_ns(…)
nvim_win_get_ns(…)
nvim_tabpage_get_ns(…)
API-CLIENT *dev-api-client*
*api-client*

View File

@ -206,7 +206,18 @@ The following new APIs and features were added.
• |'smoothscroll'| option to scroll by screen line rather than by text line
when |'wrap'| is set.
• API enhancements
• |nvim_buf_set_extmark()| supports inline virtual text.
• |nvim_win_text_height()| computes the number of screen lines occupied
by a range of text in a given window.
• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to
support fully MessagePack-RPC compliant clients.
• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
|nvim_win_set_config()|.
• |nvim_input_mouse()| supports mouse buttons "x1" and "x2".
• Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
• |nvim__win_add_ns()| can bind a |namespace| to a window-local scope(s).
• Extmarks opt-in to this scoping via the `scoped` flag of |nvim_buf_set_extmark()|.
• 'foldtext' now supports virtual text format. |fold-foldtext|
@ -218,9 +229,6 @@ The following new APIs and features were added.
• |vim.lpeg| and |vim.re| expose the bundled Lpeg expression grammar parser
and its regex interface.
• |nvim_win_text_height()| computes the number of screen lines occupied
by a range of text in a given window.
• Mapping APIs now support abbreviations when mode short-name has suffix "a".
• Better cmdline completion for string option value. |complete-set-option|
@ -321,15 +329,9 @@ The following new APIs and features were added.
• Functions that take a severity as an optional parameter (e.g.
|vim.diagnostic.get()|) now also accept a list of severities |vim.diagnostic.severity|
• New RPC client type `msgpack-rpc` is added for |nvim_set_client_info()| to
support fully MessagePack-RPC compliant clients.
• Floating windows can now show footer with new `footer` and `footer_pos`
config fields. Uses |hl-FloatFooter| by default.
• Floating windows can now be hidden by setting `hide` in |nvim_open_win()| or
|nvim_win_set_config()|.
• |:terminal| command now accepts some |:command-modifiers| (specifically
|:horizontal| and those that affect splitting a window).
@ -360,8 +362,6 @@ The following new APIs and features were added.
• 'completeopt' option supports "popup" flag to show extra information in a
floating window.
• |nvim_input_mouse()| supports mouse buttons "x1" and "x2".
• |v_Q-default| and |v_@-default| repeat a register for each line of a linewise
visual selection.
@ -386,14 +386,8 @@ The following new APIs and features were added.
using the OSC 8 control sequence, enabling clickable text in supporting
terminals.
• Added |nvim_tabpage_set_win()| to set the current window of a tabpage.
• Clicking on a tabpage in the tabline with the middle mouse button closes it.
• |namespace| can now have window scopes. |nvim_win_add_ns()|
• |extmarks| option `scoped`: only show the extmarks in its namespace's scope.
• Added built-in |commenting| support.
• |vim.fs.root()| finds project root directories from a list of "root

View File

@ -144,6 +144,36 @@ function vim.api.nvim__stats() end
--- @return any
function vim.api.nvim__unpack(str) end
--- @private
--- EXPERIMENTAL: this API will change in the future.
---
--- Scopes a namespace to the a window, so extmarks in the namespace will be
--- active only in the given window.
---
--- @param window integer Window handle, or 0 for current window
--- @param ns_id integer Namespace
--- @return boolean
function vim.api.nvim__win_add_ns(window, ns_id) end
--- @private
--- EXPERIMENTAL: this API will change in the future.
---
--- Unscopes a namespace (un-binds it from the given scope).
---
--- @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_del_ns(window, ns_id) end
--- @private
--- EXPERIMENTAL: this API will change in the future.
---
--- Gets the namespace scopes for a given window.
---
--- @param window integer Window handle, or 0 for current window
--- @return integer[]
function vim.api.nvim__win_get_ns(window) end
--- Adds a highlight to buffer.
---
--- Useful for plugins that dynamically generate highlights to a buffer (like
@ -656,8 +686,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)
--- • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
--- extmark. See `nvim__win_add_ns()`
--- @return integer
function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
@ -2114,13 +2144,6 @@ 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
@ -2173,12 +2196,6 @@ 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
@ -2232,13 +2249,6 @@ 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

View File

@ -129,7 +129,7 @@ function M.on_yank(opts)
yank_cancel()
end
vim.api.nvim_win_add_ns(winid, yank_ns)
vim.api.nvim__win_add_ns(winid, yank_ns)
M.range(bufnr, yank_ns, higroup, "'[", "']", {
regtype = event.regtype,
inclusive = event.inclusive,
@ -141,7 +141,7 @@ function M.on_yank(opts)
yank_timer = nil
yank_cancel = nil
pcall(vim.api.nvim_buf_clear_namespace, bufnr, yank_ns, 0, -1)
pcall(vim.api.nvim_win_remove_ns, winid, yank_ns)
pcall(vim.api.nvim__win_del_ns, winid, yank_ns)
end
yank_timer = vim.defer_fn(yank_cancel, timeout)

View File

@ -489,8 +489,8 @@ Array nvim_buf_get_extmarks(Buffer buffer, Integer ns_id, Object start, Object e
/// 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.
/// - scoped: boolean that indicates that the extmark should only be
/// displayed in the namespace scope. (experimental)
/// - scoped: boolean (EXPERIMENTAL) enables "scoping" for the extmark. See
/// |nvim__win_add_ns()|
///
/// @param[out] err Error details, if any
/// @return Id of the created/updated extmark
@ -1215,13 +1215,15 @@ String nvim__buf_debug_extmarks(Buffer buffer, Boolean keys, Boolean dot, Error
return mt_inspect(buf->b_marktree, keys, dot);
}
/// Adds the namespace scope to the window.
/// EXPERIMENTAL: this API will change in the future.
///
/// Scopes a namespace to the a window, so extmarks in the namespace will be active only in the
/// given window.
///
/// @param window Window handle, or 0 for current window
/// @param ns_id the namespace to add
/// @param ns_id Namespace
/// @return true if the namespace was added, else false
Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err)
FUNC_API_SINCE(12)
Boolean nvim__win_add_ns(Window window, Integer ns_id, Error *err)
{
win_T *win = find_window_by_handle(window, err);
if (!win) {
@ -1241,12 +1243,13 @@ Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err)
return true;
}
/// Gets all the namespaces scopes associated with a window.
/// EXPERIMENTAL: this API will change in the future.
///
/// Gets the namespace scopes for a given window.
///
/// @param window Window handle, or 0 for current window
/// @return a list of namespaces ids
ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err)
FUNC_API_SINCE(12)
ArrayOf(Integer) nvim__win_get_ns(Window window, Arena *arena, Error *err)
{
win_T *win = find_window_by_handle(window, err);
if (!win) {
@ -1262,13 +1265,14 @@ ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err)
return rv;
}
/// Removes the namespace scope from the window.
/// EXPERIMENTAL: this API will change in the future.
///
/// Unscopes a namespace (un-binds it from the given scope).
///
/// @param window Window handle, or 0 for current window
/// @param ns_id the namespace to remove
/// @return true if the namespace was removed, else false
Boolean nvim_win_remove_ns(Window window, Integer ns_id, Error *err)
FUNC_API_SINCE(12)
Boolean nvim__win_del_ns(Window window, Integer ns_id, Error *err)
{
win_T *win = find_window_by_handle(window, err);
if (!win) {

View File

@ -43,9 +43,9 @@ describe('vim.highlight.on_yank', function()
vim.api.nvim_buf_set_mark(0,"]",1,1,{})
vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
]])
neq({}, api.nvim_win_get_ns(0))
neq({}, api.nvim__win_get_ns(0))
command('wincmd w')
eq({}, api.nvim_win_get_ns(0))
eq({}, api.nvim__win_get_ns(0))
end)
it('removes old highlight if new one is created before old one times out', function()
@ -55,7 +55,7 @@ describe('vim.highlight.on_yank', function()
vim.api.nvim_buf_set_mark(0,"]",1,1,{})
vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
]])
neq({}, api.nvim_win_get_ns(0))
neq({}, api.nvim__win_get_ns(0))
command('wincmd w')
exec_lua([[
vim.api.nvim_buf_set_mark(0,"[",1,1,{})
@ -63,6 +63,6 @@ describe('vim.highlight.on_yank', function()
vim.highlight.on_yank({timeout = math.huge, on_macro = true, event = {operator = "y"}})
]])
command('wincmd w')
eq({}, api.nvim_win_get_ns(0))
eq({}, api.nvim__win_get_ns(0))
end)
end)

View File

@ -5610,7 +5610,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5645,7 +5645,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5667,7 +5667,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5691,7 +5691,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5701,7 +5701,7 @@ describe('decorations: window scoped', function()
|
]]}
api.nvim_win_remove_ns(0, ns)
api.nvim__win_del_ns(0, ns)
screen:expect(noextmarks)
end)
@ -5716,7 +5716,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5748,7 +5748,7 @@ describe('decorations: window scoped', function()
|
]]}
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5787,7 +5787,7 @@ describe('decorations: window scoped', function()
|
]]}
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5815,7 +5815,7 @@ describe('decorations: window scoped', function()
screen:expect(noextmarks)
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5836,7 +5836,7 @@ describe('decorations: window scoped', function()
end_col = 3,
})
api.nvim_win_add_ns(0, ns)
api.nvim__win_add_ns(0, ns)
screen:expect {
grid = [[
@ -5880,8 +5880,8 @@ describe('decorations: window scoped', function()
end_col = 3,
})
eq(true, api.nvim_win_add_ns(0, ns))
eq({ ns }, api.nvim_win_get_ns(0))
eq(true, api.nvim__win_add_ns(0, ns))
eq({ ns }, api.nvim__win_get_ns(0))
screen:expect {
grid = [[
@ -5892,12 +5892,12 @@ describe('decorations: window scoped', function()
command 'split'
command 'only'
eq({}, api.nvim_win_get_ns(0))
eq({}, api.nvim__win_get_ns(0))
screen:expect(noextmarks)
eq(true, api.nvim_win_add_ns(0, ns))
eq({ ns }, api.nvim_win_get_ns(0))
eq(true, api.nvim__win_add_ns(0, ns))
eq({ ns }, api.nvim__win_get_ns(0))
screen:expect {
grid = [[
@ -5906,8 +5906,8 @@ describe('decorations: window scoped', function()
|
]]}
eq(true, api.nvim_win_remove_ns(0, ns))
eq({}, api.nvim_win_get_ns(0))
eq(true, api.nvim__win_del_ns(0, ns))
eq({}, api.nvim__win_get_ns(0))
screen:expect(noextmarks)
end)