fix(treesitter): return full metadata for get_captures_at_position (#20203)

fix(treesitter): get_captures_at_position returns metadata

Return the full `metadata` table for the capture instead of just the
priority.

Further cleanup of related docs.

runtime/doc/treesitter.txt

@@ -203,7 +203,7 @@ purpose, e.g., `queries/lua/highlights.scm` for highlighting Lua files.
 By default, the first query on `runtimepath` is used (which usually implies
 that user config takes precedence over plugins, which take precedence over
 queries bundled with Neovim). If a query should extend other queries instead
-of replacing them, use |ts-query-modeline-extends|.
+of replacing them, use |treesitter-query-modeline-extends|.
 
 See |lua-treesitter-query| for the list of available methods for working with
 treesitter queries from Lua.
@@ -220,28 +220,28 @@ to only match identifier corresponding to the `"foo"` text.
 
 The following predicates are built in:
 
-    `eq?`                                                   *ts-predicate-eq?*
+    `eq?`                                            *treesitter-predicate-eq?*
         Match a string against the text corresponding to a node: >
             ((identifier) @foo (#eq? @foo "foo"))
             ((node1) @left (node2) @right (#eq? @left @right))
 <
-    `match?`                                        *ts-predicate-match?*
+    `match?`                                      *treesitter-predicate-match?*
-    `vim-match?`                                    *ts-predicate-vim-match?*
+    `vim-match?`                              *treesitter-predicate-vim-match?*
          Match a |regexp| against the text corresponding to a node: >
             ((identifier) @constant (#match? @constant "^[A-Z_]+$"))
 <         Note: The `^` and `$` anchors will match the start and end of the
                node's text.
 
-    `lua-match?`                                    *ts-predicate-lua-match?*
+    `lua-match?`                              *treesitter-predicate-lua-match?*
          Match a |lua-pattern| against the text corresponding to a node,
          similar to `match?`
 
-    `contains?`                                     *ts-predicate-contains?*
+    `contains?`                                *treesitter-predicate-contains?*
         Match a string against parts of the text corresponding to a node: >
             ((identifier) @foo (#contains? @foo "foo"))
             ((identifier) @foo-bar (#contains @foo-bar "foo" "bar"))
 <
-    `any-of?`                                       *ts-predicate-any-of?*
+    `any-of?`                                    *treesitter-predicate-any-of?*
         Match any of the given strings against the text corresponding to
         a node: >
             ((identifier) @foo (#any-of? @foo "foo" "bar"))
@@ -267,7 +267,7 @@ effects. For example, the |set!| predicate sets metadata on the match or node: >
 <
 The following directives are built in:
 
-    `set!`                                                  *ts-directive-set!*
+    `set!`                                          *treesitter-directive-set!*
         Sets key/value metadata for a specific match or capture. Value is
         accessible as either `metadata[key]` (match specific) or
         `metadata[capture_id][key]` (capture specific).
@@ -281,7 +281,7 @@ The following directives are built in:
             ((identifier) @foo (#set! @foo "kind" "parameter"))
             ((node1) @left (node2) @right (#set! "type" "pair"))
 <
-    `offset!`                                           *ts-directive-offset!*
+    `offset!`                                      *treesitter-directive-offset!*
         Takes the range of the captured node and applies an offset. This will
         generate a new range object for the captured node as
         `metadata[capture_id].range`.
@@ -302,13 +302,13 @@ Use `vim.treesitter.query.`|list_directives()| to list all available
 directives.
 
 
-TREESITTER QUERY MODELINES                                 *ts-query-modeline*
+TREESITTER QUERY MODELINES                          *treesitter-query-modeline*
 
 Neovim supports to customize the behavior of the queries using a set of
 "modelines", that is comments in the queries starting with `;`. Here are the
 currently supported modeline alternatives:
 
-    `inherits: {lang}...`                           *ts-query-modeline-inherits*
+    `inherits: {lang}...`                     *treesitter-query-modeline-inherits*
         Specifies that this query should inherit the queries from {lang}.
         This will recursively descend in the queries of {lang} unless wrapped
         in parentheses: `({lang})`.
@@ -316,7 +316,7 @@ currently supported modeline alternatives:
         language. If you want your query to extend the queries of the same
         language, use `extends`.
 
-    `extends`                                        *ts-query-modeline-extends*
+    `extends`                                  *treesitter-query-modeline-extends*
         Specifies that this query should be used as an extension for the
         query, i.e. that it should be merged with the others.
         Note: The order of the extensions, and the query that will be used as
@@ -436,14 +436,20 @@ get_captures_at_cursor({winnr})                     *get_captures_at_cursor()*
 
                                                   *get_captures_at_position()*
 get_captures_at_position({bufnr}, {row}, {col})
+    Returns a list of highlight captures at the given position
+
+    Each capture is represented by a table containing the capture name as a
+    string as well as a table of metadata (`priority`, `conceal`, ...; empty
+    if none are defined).
+
     Parameters: ~
         {bufnr}  (number) Buffer number (0 for current buffer)
         {row}    (number) Position row
         {col}    (number) Position column
 
     Return: ~
-        table[] Captures of the form `{ capture = "capture name", priority =
+        table[] List of captures `{ capture = "capture name", metadata = { ...
-        capture priority }`
+        } }`
 
 get_node_at_cursor({winnr})                             *get_node_at_cursor()*
     Returns the smallest named node under the cursor

runtime/lua/vim/treesitter.lua

@@ -154,7 +154,7 @@ function M.get_node_range(node_or_range)
   end
 end
 
----Determines whether (line, col) position is in node range
+--- Determines whether (line, col) position is in node range
 ---
 ---@param node userdata |tsnode| defining the range
 ---@param line number Line (0-based)
@@ -178,7 +178,8 @@ function M.is_in_node_range(node, line, col)
   end
 end
 
----Determines if a node contains a range
+--- Determines if a node contains a range
+---
 ---@param node userdata |tsnode|
 ---@param range table
 ---
@@ -191,17 +192,16 @@ function M.node_contains(node, range)
   return start_fits and end_fits
 end
 
----Returns a list of highlight captures at the given position
+--- Returns a list of highlight captures at the given position
---
+---
----@param bufnr number Buffer number (0 for current buffer)
+--- Each capture is represented by a table containing the capture name as a string as
----@param row number Position row
+--- well as a table of metadata (`priority`, `conceal`, ...; empty if none are defined).
----@param col number Position column
 ---
 ---@param bufnr number Buffer number (0 for current buffer)
 ---@param row number Position row
 ---@param col number Position column
 ---
----@return table[] Captures of the form `{ capture = "capture name", priority = capture priority }`
+---@return table[] List of captures `{ capture = "capture name", metadata = { ... } }`
 function M.get_captures_at_position(bufnr, row, col)
   if bufnr == 0 then
     bufnr = a.nvim_get_current_buf()
@@ -240,7 +240,7 @@ function M.get_captures_at_position(bufnr, row, col)
       if M.is_in_node_range(node, row, col) then
         local c = q._query.captures[capture] -- name of the capture in the query
         if c ~= nil then
-          table.insert(matches, { capture = c, priority = metadata.priority })
+          table.insert(matches, { capture = c, metadata = metadata })
         end
       end
     end
@@ -248,7 +248,7 @@ function M.get_captures_at_position(bufnr, row, col)
   return matches
 end
 
----Returns a list of highlight capture names under the cursor
+--- Returns a list of highlight capture names under the cursor
 ---
 ---@param winnr (number|nil) Window handle or 0 for current window (default)
 ---

test/functional/treesitter/highlight_spec.lua

@@ -605,8 +605,8 @@ describe('treesitter highlighting', function()
     }}
 
     eq({
-      {capture='Error', priority='101'};
+      {capture='Error', metadata = { priority='101' }};
-      {capture='type'};
+      {capture='type', metadata = { } };
     }, exec_lua [[ return vim.treesitter.get_captures_at_position(0, 0, 2) ]])
     end)