Merge pull request #13243 from bfredl/intersection

feat(extmark): support highlighting and querying multiline ranges

2 files changed, 21 insertions, 1 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 9cdfd8a563..34e2aedabf 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2546,7 +2546,7 @@ nvim_buf_get_extmark_by_id({buffer}, {ns_id}, {id}, {opts})
         0-indexed (row, col) tuple or empty list () if extmark id was absent
 
                                                      *nvim_buf_get_extmarks()*
-nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
+nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {*opts})
     Gets |extmarks| in "traversal order" from a |charwise| region defined by
     buffer positions (inclusive, 0-indexed |api-indexing|).
 
@@ -2560,6 +2560,10 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
     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
       local pos = api.nvim_win_get_cursor(0)
@@ -2589,6 +2593,8 @@ nvim_buf_get_extmarks({buffer}, {ns_id}, {start}, {end}, {opts})
                   • 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"
 
@@ -2608,6 +2614,11 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
     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).
+
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer
       • {ns_id}   Namespace id from |nvim_create_namespace()|
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index cd977a8b5f..93012e78a9 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -221,6 +221,15 @@ The following changes to existing APIs or features add new behavior.
   "virtual_text" table, which gives users more control over how diagnostic
   virtual text is displayed.
 
+• Extmarks now fully support multi-line ranges, and a single extmark can be
+  used to highlight a range of arbitrary length. The |nvim_buf_set_extmark()|
+  API function already allowed you to define such ranges, but highlight regions
+  were not rendered consistently for a range that covers more than one line break.
+  This has now been fixed. Signs defined as part of a multi-line extmark also
+  apply to every line in the range, not just the first.
+  In addition, |nvim_buf_get_extmarks()| has gained an "overlap" option to
+  return such ranges even if they started before the specified position.
+
 ==============================================================================
 REMOVED FEATURES                                                 *news-removed*