Merge pull request #19931 from bfredl/scopedhl

feat(highlight)!: use scoped @foo.bar.special groups for tree-sitter highlight

1 files changed, 46 insertions, 8 deletions

diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index c80d8f4479..2c6c9e4ed8 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -323,16 +323,34 @@ for a buffer with this code: >
     local query2 = [[ ... ]]
     highlighter:set_query(query2)
 
-As mentioned above the supported predicate is currently only `eq?`. `match?`
-predicates behave like matching always fails. As an addition a capture which
-begin with an upper-case letter like `@WarningMsg` will map directly to this
-highlight group, if defined. Also if the predicate begins with upper-case and
-contains a dot only the part before the first will be interpreted as the
-highlight group. As an example, this warns of a binary expression with two
+
+                                             *lua-treesitter-highlight-groups*
+The capture names, with `@` included, are directly usable as highlight groups.
+A fallback system is implemented, so that more specific groups fallback to
+more generic ones. For instance, in a language that has separate doc
+comments, `@comment.doc` could be used. If this group is not defined, the
+highlighting for an ordinary `@comment` is used. This way, existing color
+schemes already work out of the box, but it is possible to add
+more specific variants for queries that make them available.
+
+As an additional rule, captures highlights can always be specialized by
+language, by appending the language name after an additional dot. For
+instance, to highlight comments differently per language: >
+
+    hi @comment.c guifg=Blue
+    hi @comment.lua @guifg=DarkBlue
+    hi link @comment.doc.java String
+<
+It is possible to use custom highlight groups. As an example, if we
+define the `@warning` group: >
+
+    hi link @warning WarningMsg
+<
+the following query warns of a binary expression with two
 identical identifiers, highlighting both as |hl-WarningMsg|: >
 
-    ((binary_expression left: (identifier) @WarningMsg.left right: (identifier) @WarningMsg.right)
-     (eq? @WarningMsg.left @WarningMsg.right))
+    ((binary_expression left: (identifier) @warning.left right: (identifier) @warning.right)
+     (eq? @warning.left @warning.right))
 <
 Treesitter Highlighting Priority            *lua-treesitter-highlight-priority*
 
@@ -352,6 +370,18 @@ attribute: >
 ==============================================================================
 Lua module: vim.treesitter                               *lua-treesitter-core*
 
+                                                  *get_captures_at_position()*
+get_captures_at_position({bufnr}, {row}, {col})
+    Gets a list of captures for a given cursor position
+
+    Parameters: ~
+        {bufnr}  (number) The buffer number
+        {row}    (number) The position row
+        {col}    (number) The position column
+
+    Return: ~
+        (table) A table of captures
+
 get_node_range({node_or_range})                             *get_node_range()*
     Get the node's range or unpack a range table
 
@@ -393,6 +423,14 @@ is_ancestor({dest}, {source})                                  *is_ancestor()*
     Return: ~
         (boolean) True if dest is an ancestor of source
 
+is_in_node_range({node}, {line}, {col})                   *is_in_node_range()*
+    Determines whether (line, col) position is in node range
+
+    Parameters: ~
+        {node}  Node defining the range
+        {line}  A line (0-based)
+        {col}   A column (0-based)
+
 node_contains({node}, {range})                               *node_contains()*
     Determines if a node contains a range