diff options
| -rw-r--r-- | runtime/doc/api.txt | 23 | ||||
| -rw-r--r-- | runtime/doc/develop.txt | 77 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 30 | ||||
| -rw-r--r-- | runtime/lua/vim/_meta/api.lua | 25 | ||||
| -rw-r--r-- | runtime/lua/vim/highlight.lua | 2 | ||||
| -rw-r--r-- | src/nvim/api/extmark.c | 15 | ||||
| -rw-r--r-- | test/functional/ui/decorations_spec.lua | 4 |
7 files changed, 114 insertions, 62 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 86f4c3875c..f593f14929 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -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 @@ -2860,33 +2860,34 @@ nvim_set_decoration_provider({ns_id}, {opts}) < nvim_win_add_ns({window}, {ns_id}) *nvim_win_add_ns()* - Adds the namespace scope to the window. + 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()* + Unscopes a namespace (un-binds it from the given scope). Parameters: ~ • {window} Window handle, or 0 for current window + • {ns_id} the namespace to remove Return: ~ - a list of namespaces ids + true if the namespace was removed, else false -nvim_win_remove_ns({window}, {ns_id}) *nvim_win_remove_ns()* - Removes the namespace scope from the window. +nvim_win_get_ns({window}) *nvim_win_get_ns()* + Gets the namespace scopes for a given window. Parameters: ~ • {window} Window handle, or 0 for current window - • {ns_id} the namespace to remove Return: ~ - true if the namespace was removed, else false + a list of namespaces ids ============================================================================== diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index 7fc154441f..11c25362b6 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -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* diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index 111e69b0fe..b6add63595 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -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. -• |nvim_buf_set_extmark()| supports inline virtual text. +• 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 diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 64c67be076..dbd3c61634 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -656,8 +656,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,10 +2114,11 @@ 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. +--- 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 the namespace to add +--- @param ns_id integer Namespace --- @return boolean function vim.api.nvim_win_add_ns(window, ns_id) end @@ -2137,6 +2138,13 @@ function vim.api.nvim_win_call(window, fun) end --- hidden, even if 'hidden' is not set. function vim.api.nvim_win_close(window, force) end +--- 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 + --- Removes a window-scoped (w:) variable --- --- @param window integer Window handle, or 0 for current window @@ -2173,7 +2181,7 @@ 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. +--- Gets the namespace scopes for a given window. --- --- @param window integer Window handle, or 0 for current window --- @return integer[] @@ -2232,13 +2240,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 diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua index 781fabe5fb..da3d7fd361 100644 --- a/runtime/lua/vim/highlight.lua +++ b/runtime/lua/vim/highlight.lua @@ -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) diff --git a/src/nvim/api/extmark.c b/src/nvim/api/extmark.c index f7c3788dad..ef40daf7bb 100644 --- a/src/nvim/api/extmark.c +++ b/src/nvim/api/extmark.c @@ -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,10 +1215,11 @@ 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. +/// 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) @@ -1241,7 +1242,7 @@ Boolean nvim_win_add_ns(Window window, Integer ns_id, Error *err) return true; } -/// Gets all the namespaces scopes associated with a window. +/// Gets the namespace scopes for a given window. /// /// @param window Window handle, or 0 for current window /// @return a list of namespaces ids @@ -1262,12 +1263,12 @@ ArrayOf(Integer) nvim_win_get_ns(Window window, Arena *arena, Error *err) return rv; } -/// Removes the namespace scope from the window. +/// 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) +Boolean nvim_win_del_ns(Window window, Integer ns_id, Error *err) FUNC_API_SINCE(12) { win_T *win = find_window_by_handle(window, err); diff --git a/test/functional/ui/decorations_spec.lua b/test/functional/ui/decorations_spec.lua index 244e37d9d9..d285e673e9 100644 --- a/test/functional/ui/decorations_spec.lua +++ b/test/functional/ui/decorations_spec.lua @@ -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) @@ -5906,7 +5906,7 @@ describe('decorations: window scoped', function() | ]]} - eq(true, api.nvim_win_remove_ns(0, ns)) + eq(true, api.nvim_win_del_ns(0, ns)) eq({}, api.nvim_win_get_ns(0)) screen:expect(noextmarks) |