feat(treesitter): add vim.treesitter.show_tree() (#21322)

Add a "show_tree" function to view a textual representation of the
nodes in a language tree in a window. Moving the cursor in the
window highlights the corresponding text in the source buffer, and
moving the cursor in the source buffer highlights the corresponding
nodes in the window.

2 files changed, 27 insertions, 1 deletions

diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 047973242f..881faaa84e 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -39,6 +39,9 @@ NEW FEATURES                                                    *news-features*
 
 The following new APIs or features were added.
 
+• |vim.treesitter.show_tree()| opens a split window showing a text
+  representation of the nodes in a language tree for the current buffer.
+
 • Added support for the `willSave` and `willSaveWaitUntil` capabilities to the
   LSP client. `willSaveWaitUntil` allows a server to modify a document before it
   gets saved. Example use-cases by language servers include removing unused
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index 869ed8a187..71a5fdaad0 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -530,7 +530,7 @@ get_node_at_pos({bufnr}, {row}, {col}, {opts})
                    (default true)
 
     Return: ~
-        userdata |tsnode| under the cursor
+        userdata|nil |tsnode| under the cursor
 
 get_node_range({node_or_range})              *vim.treesitter.get_node_range()*
     Returns the node's range or an unpacked range table
@@ -601,6 +601,29 @@ node_contains({node}, {range})                *vim.treesitter.node_contains()*
     Return: ~
         (boolean) True if the {node} contains the {range}
 
+show_tree({opts})                                 *vim.treesitter.show_tree()*
+    Open a window that displays a textual representation of the nodes in the
+    language tree.
+
+    While in the window, press "a" to toggle display of anonymous nodes, "I"
+    to toggle the display of the source language of each node, and press
+    <Enter> to jump to the node under the cursor in the source buffer.
+
+    Parameters: ~
+      • {opts}  (table|nil) Optional options table with the following possible
+                keys:
+                • bufnr (number|nil): Buffer to draw the tree into. If
+                  omitted, a new buffer is created.
+                • winid (number|nil): Window id to display the tree buffer in.
+                  If omitted, a new window is created with {command}.
+                • command (string|nil): Vimscript command to create the
+                  window. Default value is "topleft 60vnew". Only used when
+                  {winid} is nil.
+                • title (string|fun(bufnr:number):string|nil): Title of the
+                  window. If a function, it accepts the buffer number of the
+                  source buffer as its only argument and should return a
+                  string.
+
 start({bufnr}, {lang})                                *vim.treesitter.start()*
     Starts treesitter highlighting for a buffer