feat(extmarks): add 'invalidate' property to extmarks

Problem:  No way to have extmarks automatically removed when the range it
          is attached to is deleted.
Solution: Add new 'invalidate' property that will hide a mark when the
          entirety of its range is deleted. When "undo_restore" is set
          to false, delete the mark from the buffer instead.

1 files changed, 7 insertions, 1 deletions

diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index 691da62f4f..6c6e11a0d3 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -554,6 +554,12 @@ function vim.api.nvim_buf_line_count(buffer) end
 ---                 the extmark end position (if it exists) will be shifted in
 ---                 when new text is inserted (true for right, false for
 ---                 left). Defaults to false.
+---               • undo_restore : Restore the exact position of the mark if
+---                 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
+---                 "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.
@@ -1812,7 +1818,7 @@ function vim.api.nvim_set_current_win(window) end
 --- `nvim_buf_set_extmark()` can be called to add marks on a per-window or
 --- per-lines basis. Use the `ephemeral` key to only use the mark for the
 --- current screen redraw (the callback will be called again for the next
---- redraw ).
+--- redraw).
 --- Note: this function should not be called often. Rather, the callbacks
 --- themselves can be used to throttle unneeded callbacks. the `on_start`
 --- callback can return `false` to disable the provider until the next redraw.