refactor(highlight)!: optional arguments for highlight.range as table (#17462)

also update documentation

BREAKING CHANGE: signature of highlight.range is now
     vim.highlight.range(bufnr, ns, hlgroup, start, finish,
         { regtype = regtype, inclusive = inclusive, priority = priority })

Co-authored-by: Gregory Anders <8965202+gpanders@users.noreply.github.com>

runtime/doc/lua.txt

@@ -595,13 +595,33 @@ vim.highlight.on_yank({opts})                         *vim.highlight.on_yank()*
           - {on_visual} highlight when yanking visual selection (default `true`)
           - {event} event structure (default |v:event|)
 
-vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive})
+vim.highlight.range({bufnr}, {ns}, {hlgroup}, {start}, {finish}, {opts})
                                                        *vim.highlight.range()*
-        Highlights the range between {start} and {finish} (tuples of {line,col})
+
-        in buffer {bufnr} with the highlight group {higroup} using the namespace
+        Apply highlight group to range of text.
-        {ns}. Optional arguments are the type of range (characterwise, linewise,
+
-        or blockwise, see |setreg|; default to characterwise) and whether the
+                Parameters: ~
-        range is inclusive (default false).
+                    {bufnr}   buffer number
+                    {ns}      namespace for highlights
+                    {hlgroup} highlight group name
+                    {start}   starting position (tuple {line,col})
+                    {finish}  finish position (tuple {line,col})
+                    {opts}    optional parameters:
+                              • `regtype`: type of range (characterwise, linewise,
+                                or blockwise, see |setreg|), default `'v'`
+                              • `inclusive`: range includes end position, default
+                                `false`
+                              • `priority`: priority of highlight, default
+                                `vim.highlight.user` (see below)
+
+vim.highlight.priorities                           *vim.highlight.priorities*
+
+        Table with default priorities used for highlighting:
+            • `syntax`: `50`, used for standard syntax highlighting
+            • `treesitter`: `100`, used for tree-sitter-based highlighting
+            • `diagnostics`: `150`, used for code analysis such as diagnostics
+            • `user`: `200`, used for user-triggered highlights such as LSP
+              document symbols or `on_yank` autocommands
 
 ------------------------------------------------------------------------------
 VIM.REGEX                                                       *lua-regex*

runtime/lua/vim/diagnostic.lua

@@ -921,9 +921,7 @@ M.handlers.underline = {
         higroup,
         { diagnostic.lnum, diagnostic.col },
         { diagnostic.end_lnum, diagnostic.end_col },
-        'v',
+        { priority = vim.highlight.priorities.diagnostics }
-        false,
-        150
       )
     end
     save_extmarks(underline_ns, bufnr)

runtime/lua/vim/highlight.lua

@@ -1,9 +1,16 @@
 local api = vim.api
 
-local highlight = {}
+local M = {}
+
+M.priorities = {
+  syntax = 50,
+  treesitter = 100,
+  diagnostics = 150,
+  user = 200,
+}
 
 ---@private
-function highlight.create(higroup, hi_info, default)
+function M.create(higroup, hi_info, default)
   local options = {}
   -- TODO: Add validation
   for k, v in pairs(hi_info) do
@@ -13,28 +20,33 @@ function highlight.create(higroup, hi_info, default)
 end
 
 ---@private
-function highlight.link(higroup, link_to, force)
+function M.link(higroup, link_to, force)
   vim.cmd(string.format([[highlight%s link %s %s]], force and "!" or " default", higroup, link_to))
 end
 
-
 --- Highlight range between two positions
 ---
 ---@param bufnr number of buffer to apply highlighting to
 ---@param ns namespace to add highlight to
 ---@param higroup highlight group to use for highlighting
----@param rtype type of range (:help setreg, default charwise)
+---@param start first position (tuple {line,col})
----@param inclusive boolean indicating whether the range is end-inclusive (default false)
+---@param finish second position (tuple {line,col})
----@param priority number indicating priority of highlight (default 50)
+---@param opts table with options:
-function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive, priority)
+--             - regtype type of range (:help setreg, default charwise)
-  rtype = rtype or 'v'
+--             - inclusive boolean indicating whether the range is end-inclusive (default false)
-  inclusive = inclusive or false
+--             - priority number indicating priority of highlight (default priorities.user)
-  priority = priority or 50
+function M.range(bufnr, ns, higroup, start, finish, opts)
+  opts = opts or {}
+  local regtype = opts.regtype or "v"
+  local inclusive = opts.inclusive or false
+  local priority = opts.priority or M.priorities.user
 
   -- sanity check
-  if start[2] < 0 or finish[1] < start[1] then return end
+  if start[2] < 0 or finish[1] < start[1] then
+    return
+  end
 
-  local region = vim.region(bufnr, start, finish, rtype, inclusive)
+  local region = vim.region(bufnr, start, finish, regtype, inclusive)
   for linenr, cols in pairs(region) do
     local end_row
     if cols[2] == -1 then
@@ -46,13 +58,12 @@ function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive, pr
       end_row = end_row,
       end_col = cols[2],
       priority = priority,
-      strict = false
+      strict = false,
     })
   end
-
 end
 
-local yank_ns = api.nvim_create_namespace('hlyank')
+local yank_ns = api.nvim_create_namespace("hlyank")
 --- Highlight the yanked region
 ---
 --- use from init.vim via
@@ -62,26 +73,40 @@ local yank_ns = api.nvim_create_namespace('hlyank')
 --- customize conditions (here: do not highlight a visual selection) via
 ---   au TextYankPost * lua vim.highlight.on_yank {on_visual=false}
 ---
--- @param opts dictionary with options controlling the highlight:
+-- @param opts table with options controlling the highlight:
 --              - higroup   highlight group for yanked region (default "IncSearch")
 --              - timeout   time in ms before highlight is cleared (default 150)
 --              - on_macro  highlight when executing macro (default false)
 --              - on_visual highlight when yanking visual selection (default true)
 --              - event     event structure (default vim.v.event)
-function highlight.on_yank(opts)
+function M.on_yank(opts)
-  vim.validate {
+  vim.validate({
-    opts = { opts,
+    opts = {
-    function(t) if t == nil then return true else return type(t) == 'table' end end,
+      opts,
-    'a table or nil to configure options (see `:h highlight.on_yank`)',
+      function(t)
-  }}
+        if t == nil then
+          return true
+        else
+          return type(t) == "table"
+        end
+      end,
+      "a table or nil to configure options (see `:h highlight.on_yank`)",
+    },
+  })
   opts = opts or {}
   local event = opts.event or vim.v.event
   local on_macro = opts.on_macro or false
   local on_visual = (opts.on_visual ~= false)
 
-  if (not on_macro) and vim.fn.reg_executing() ~= '' then return end
+  if not on_macro and vim.fn.reg_executing() ~= "" then
-  if event.operator ~= 'y' or event.regtype == '' then return end
+    return
-  if (not on_visual) and event.visual then return end
+  end
+  if event.operator ~= "y" or event.regtype == "" then
+    return
+  end
+  if not on_visual and event.visual then
+    return
+  end
 
   local higroup = opts.higroup or "IncSearch"
   local timeout = opts.timeout or 150
@@ -92,19 +117,23 @@ function highlight.on_yank(opts)
   local pos1 = vim.fn.getpos("'[")
   local pos2 = vim.fn.getpos("']")
 
-  pos1 = {pos1[2] - 1, pos1[3] - 1 + pos1[4]}
+  pos1 = { pos1[2] - 1, pos1[3] - 1 + pos1[4] }
-  pos2 = {pos2[2] - 1, pos2[3] - 1 + pos2[4]}
+  pos2 = { pos2[2] - 1, pos2[3] - 1 + pos2[4] }
 
-  highlight.range(bufnr, yank_ns, higroup, pos1, pos2, event.regtype, event.inclusive, 200)
+  M.range(
-
+    bufnr,
-  vim.defer_fn(
+    yank_ns,
-    function()
+    higroup,
-      if api.nvim_buf_is_valid(bufnr) then
+    pos1,
-        api.nvim_buf_clear_namespace(bufnr, yank_ns, 0, -1)
+    pos2,
-      end
+    { regtype = event.regtype, inclusive = event.inclusive, priority = M.priorities.user }
-    end,
-    timeout
   )
+
+  vim.defer_fn(function()
+    if api.nvim_buf_is_valid(bufnr) then
+      api.nvim_buf_clear_namespace(bufnr, yank_ns, 0, -1)
+    end
+  end, timeout)
 end
 
-return highlight
+return M

runtime/lua/vim/lsp/util.lua

@@ -1551,9 +1551,7 @@ do --[[ References ]]
                       document_highlight_kind[kind],
                       { start_line, start_idx },
                       { end_line, end_idx },
-                      'v',
+                      { priority = vim.highlight.priorities.user })
-                      false,
-                      200)
     end
   end
 end