Merge pull request #15114 from theHamsta/treesitter-hl-priority

feat(treesitter): allow to set highlight priority for queries

runtime/doc/api.txt

@@ -2334,8 +2334,9 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                                 inserted (true for right, false for left).
                                 Defaults to false.
                               • priority: a priority value for the highlight
-                                group. For example treesitter highlighting
+                                group. Default: 4096. For example, treesitter
-                                uses a value of 100.
+                                highlighting uses a default value of 100 (see
+                                |lua-treesitter-highlight-priority|).
 
                 Return: ~
                     Id of the created/updated extmark

runtime/doc/treesitter.txt

@@ -294,6 +294,19 @@ identical identifiers, highlighting both as |hl-WarningMsg|: >
     ((binary_expression left: (identifier) @WarningMsg.left right: (identifier) @WarningMsg.right)
      (eq? @WarningMsg.left @WarningMsg.right))
 <
+Treesitter Highlighting Priority            *lua-treesitter-highlight-priority*
+
+Tree-sitter uses |nvim_buf_set_extmark()| to set highlights with a default 
+priority of 100. This enables plugins to set a highlighting priority lower or
+higher than tree-sitter. It is also possible to change the priority of an
+individual query pattern manually by setting its `"priority"` metadata attribute: >
+
+    (
+      (super_important_node) @ImportantHighlight
+      ; Give the whole query highlight priority higher than the default (100)
+      (set! "priority" 105)
+    )
+<
 
 ==============================================================================
 Lua module: vim.treesitter                               *lua-treesitter-core*

runtime/lua/vim/treesitter/highlighter.lua

@@ -248,7 +248,7 @@ local function on_line_impl(self, buf, line)
     end
 
     while line >= state.next_row do
-      local capture, node = state.iter()
+      local capture, node, metadata = state.iter()
 
       if capture == nil then break end
 
@@ -260,7 +260,7 @@ local function on_line_impl(self, buf, line)
                                { end_line = end_row, end_col = end_col,
                                  hl_group = hl,
                                  ephemeral = true,
-                                 priority = 100 -- Low but leaves room below
+                                 priority = tonumber(metadata.priority) or 100 -- Low but leaves room below
                                 })
       end
       if start_row > line then

test/functional/treesitter/highlight_spec.lua

@@ -570,4 +570,47 @@ describe('treesitter highlighting', function()
     ]]}
     screen:expect{ unchanged=true }
   end)
+
+  it("supports highlighting with priority", function()
+    if pending_c_parser(pending) then return end
+
+    insert([[
+    int x = INT_MAX;
+    #define READ_STRING(x, y) (char_u *)read_string((x), (size_t)(y))
+    #define foo void main() { \
+                  return 42;  \
+                }
+    ]])
+
+    exec_lua [[
+      local parser = vim.treesitter.get_parser(0, "c")
+      test_hl = vim.treesitter.highlighter.new(parser, {queries = {c = hl_query..'\n((translation_unit) @Error (set! "priority" 101))\n'}})
+    ]]
+    -- expect everything to have Error highlight
+    screen:expect{grid=[[
+      {12:int}{8: x = INT_MAX;}                                                 |
+      {8:#define READ_STRING(x, y) (char_u *)read_string((x), (size_t)(y))}|
+      {8:#define foo void main() { \}                                      |
+      {8:              return 42;  \}                                      |
+      {8:            }}                                                    |
+      ^                                                                 |
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+      {1:~                                                                }|
+                                                                       |
+    ]], attr_ids={
+      [1] = {bold = true, foreground = Screen.colors.Blue1};
+      [8] = {foreground = Screen.colors.Grey100, background = Screen.colors.Red};
+      -- bold will not be overwritten at the moment
+      [12] = {background = Screen.colors.Red, bold = true, foreground = Screen.colors.Grey100};
+    }}
+    end)
 end)