Merge pull request #13243 from bfredl/intersection

feat(extmark): support highlighting and querying multiline ranges

3 files changed, 27 insertions, 1 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index bfff16933a..7cd0d825a1 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -7,6 +7,13 @@ vim.api = {}
 
 --- @private
 --- @param buffer integer
+--- @param keys boolean
+--- @param dot boolean
+--- @return string
+function vim.api.nvim__buf_debug_extmarks(buffer, keys, dot) end
+
+--- @private
+--- @param buffer integer
 --- @param first integer
 --- @param last integer
 function vim.api.nvim__buf_redraw_range(buffer, first, last) end
@@ -313,6 +320,9 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 --- ```
 --- If `end` is less than `start`, traversal works backwards. (Useful with
 --- `limit`, to get the first marks prior to a given position.)
+--- 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.
 --- Example:
 --- ```lua
 ---   local api = vim.api
@@ -337,11 +347,13 @@ function vim.api.nvim_buf_get_extmark_by_id(buffer, ns_id, id, opts) end
 --- @param end_ any End of range (inclusive): a 0-indexed (row, col) or valid
 ---               extmark id (whose position defines the bound).
 ---               `api-indexing`
---- @param opts table<string,any> Optional parameters. Keys:
+--- @param opts vim.api.keyset.get_extmarks Optional parameters. Keys:
 ---               • limit: Maximum number of marks to return
 ---               • details: Whether to include the details dict
 ---               • hl_name: Whether to include highlight group name instead
 ---                 of id, true if omitted
+---               • overlap: Also include marks which overlap the range, even
+---                 if their start position is less than `start`
 ---               • type: Filter marks by type: "highlight", "sign",
 ---                 "virt_text" and "virt_lines"
 --- @return any[]
@@ -457,6 +469,10 @@ function vim.api.nvim_buf_line_count(buffer) end
 --- waiting for the return value.)
 --- Using the optional arguments, it is possible to use this to highlight a
 --- range of text, and also to associate virtual text to the mark.
+--- If present, the position defined by `end_col` and `end_row` should be
+--- after the start position in order for the extmark to cover a range. An
+--- earlier end position is not an error, but then it behaves like an empty
+--- range (no highlighting).
 ---
 --- @param buffer integer Buffer handle, or 0 for current buffer
 --- @param ns_id integer Namespace id from `nvim_create_namespace()`
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index 8f36edba77..4d08563ce2 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -122,6 +122,13 @@ error('Cannot require a meta file')
 --- @class vim.api.keyset.get_commands
 --- @field builtin? boolean
 
+--- @class vim.api.keyset.get_extmarks
+--- @field limit? integer
+--- @field details? boolean
+--- @field hl_name? boolean
+--- @field overlap? boolean
+--- @field type? string
+
 --- @class vim.api.keyset.get_highlight
 --- @field id? integer
 --- @field name? string
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index 14b0e71312..fd4fb54a5b 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -55,6 +55,9 @@ function M.range(bufnr, ns, higroup, start, finish, opts)
   local inclusive = opts.inclusive or false
   local priority = opts.priority or M.priorities.user
 
+  -- TODO: in case of 'v', 'V' (not block), this should calculate equivalent
+  -- bounds (row, col, end_row, end_col) as multiline regions are natively
+  -- supported now
   local region = vim.region(bufnr, start, finish, regtype, inclusive)
   for linenr, cols in pairs(region) do
     local end_row