Merge pull request #21393 from folke/highlight_show

feat(lsp): add function to get semantic tokens at cursor
feat: `vim.inspect_pos()`, `vim.show_pos()` and `:Inspect[!]`

4 files changed, 68 insertions, 1 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index d555cff443..8a33fc58a3 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -2683,7 +2683,7 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {*opts})
         Id of the created/updated extmark
 
 nvim_create_namespace({name})                        *nvim_create_namespace()*
-    Creates a new *namespace* or gets an existing one.
+    Creates a new namespace or gets an existing one.               *namespace*
 
     Namespaces are used for buffer highlights and virtual text, see
     |nvim_buf_add_highlight()| and |nvim_buf_set_extmark()|.
diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt
index 75d5c067b1..b101740b03 100644
--- a/runtime/doc/lsp.txt
+++ b/runtime/doc/lsp.txt
@@ -1332,6 +1332,19 @@ force_refresh({bufnr})               *vim.lsp.semantic_tokens.force_refresh()*
     Parameters: ~
       • {bufnr}  (nil|number) default: current buffer
 
+                                        *vim.lsp.semantic_tokens.get_at_pos()*
+get_at_pos({bufnr}, {row}, {col})
+    Return the semantic token(s) at the given position. If called without
+    arguments, returns the token under the cursor.
+
+    Parameters: ~
+      • {bufnr}  (number|nil) Buffer number (0 for current buffer, default)
+      • {row}    (number|nil) Position row (default cursor position)
+      • {col}    (number|nil) Position column (default cursor position)
+
+    Return: ~
+        (table|nil) List of tokens at position
+
 start({bufnr}, {client_id}, {opts})          *vim.lsp.semantic_tokens.start()*
     Start the semantic token highlighting engine for the given buffer with the
     given client. The client must already be attached to the buffer.
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5a1c186192..9c98ed7771 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1504,6 +1504,56 @@ schedule_wrap({cb})                                      *vim.schedule_wrap()*
         |vim.in_fast_event()|
 
 
+==============================================================================
+Lua module: inspector                                          *lua-inspector*
+
+inspect_pos({bufnr}, {row}, {col}, {filter})               *vim.inspect_pos()*
+    Get all the items at a given buffer position.
+
+    Can also be pretty-printed with `:Inspect!`.                   *:Inspect!*
+
+    Parameters: ~
+      • {bufnr}   (number|nil) defaults to the current buffer
+      • {row}     (number|nil) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (number|nil) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (table|nil) a table with key-value pairs to filter the items
+                  • syntax (boolean): include syntax based highlight groups
+                    (defaults to true)
+                  • treesitter (boolean): include treesitter based highlight
+                    groups (defaults to true)
+                  • extmarks (boolean|"all"): include extmarks. When `all`,
+                    then extmarks without a `hl_group` will also be included
+                    (defaults to true)
+                  • semantic_tokens (boolean): include semantic tokens
+                    (defaults to true)
+
+    Return: ~
+        (table) a table with the following key-value pairs. Items are in
+        "traversal order":
+        • treesitter: a list of treesitter captures
+        • syntax: a list of syntax groups
+        • semantic_tokens: a list of semantic tokens
+        • extmarks: a list of extmarks
+        • buffer: the buffer used to get the items
+        • row: the row used to get the items
+        • col: the col used to get the items
+
+show_pos({bufnr}, {row}, {col}, {filter})                     *vim.show_pos()*
+    Show all the items at a given buffer position.
+
+    Can also be shown with `:Inspect`.                              *:Inspect*
+
+    Parameters: ~
+      • {bufnr}   (number|nil) defaults to the current buffer
+      • {row}     (number|nil) row to inspect, 0-based. Defaults to the row of
+                  the current cursor
+      • {col}     (number|nil) col to inspect, 0-based. Defaults to the col of
+                  the current cursor
+      • {filter}  (table|nil) see |vim.inspect_pos()|
+
+
 
 
 deep_equal({a}, {b})                                        *vim.deep_equal()*
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index bd0d1cfc5b..e5336edb5a 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -39,6 +39,10 @@ NEW FEATURES                                                    *news-features*
 
 The following new APIs or features were added.
 
+• |vim.inspect_pos()|, |vim.show_pos()| and |:Inspect| allow a user to get or show items
+  at a given buffer postion. Currently this includes treesitter captures,
+  semantic tokens, syntax groups and extmarks.
+
 • Added support for semantic token highlighting to the LSP client. This
   functionality is enabled by default when a client that supports this feature
   is attached to a buffer. Opt-out can be performed by deleting the