From 675826da63e879efa97c0998fea192ed5c79d56e Mon Sep 17 00:00:00 2001
From: Gregory Anders <8965202+gpanders@users.noreply.github.com>
Date: Wed, 22 Feb 2023 08:01:08 -0700
Subject: refactor(treesitter): Add vim.treesitter.get_node() (#22360)

This function replaces both vim.treesitter.get_node_at_pos() and
vim.treesitter.get_node_at_cursor(). These two functions are similar
enough that they don't need separate interfaces. Even worse,
get_node_at_pos() returns a TSNode while get_node_at_cursor() returns a
string, so the two functions behave slightly differently.

vim.treesitter.get_node() combines these two into a more streamlined
interface. With no arguments, it returns the node under the cursor in
the current buffer. Optionally, it can accept a buffer number or a
position to get the node at a given position in a given buffer.
---
 runtime/doc/deprecated.txt |  8 ++++++++
 runtime/doc/news.txt       |  2 ++
 runtime/doc/treesitter.txt | 29 ++++++++++-------------------
 3 files changed, 20 insertions(+), 19 deletions(-)

(limited to 'runtime/doc')

diff --git a/runtime/doc/deprecated.txt b/runtime/doc/deprecated.txt
index e7b0a710e8..42dfb53e77 100644
--- a/runtime/doc/deprecated.txt
+++ b/runtime/doc/deprecated.txt
@@ -119,6 +119,14 @@ LSP FUNCTIONS
 - *vim.lsp.buf.range_formatting()*	Use |vim.lsp.formatexpr()|
 					or |vim.lsp.buf.format()| instead.
 
+TREESITTER FUNCTIONS
+- *vim.treesitter.language.require_language()*	Use |vim.treesitter.language.add()|
+						instead.
+- *vim.treesitter.get_node_at_pos()*		Use |vim.treesitter.get_node()|
+						instead.
+- *vim.treesitter.get_node_at_cursor()*		Use |vim.treesitter.get_node()|
+						and |TSNode:type()| instead.
+
 LUA
 - *vim.register_keystroke_callback()*	Use |vim.on_key()| instead.
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 8b41f2d104..2a12a144e6 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -208,5 +208,7 @@ release.
 • `vim.treesitter.language.require_language()` has been deprecated in favour
   of |vim.treesitter.language.add()|.
 
+• |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()|
+  are both deprecated in favor of |vim.treesitter.get_node()|.
 
  vim:tw=78:ts=8:sw=2:et:ft=help:norl:
diff --git a/runtime/doc/treesitter.txt b/runtime/doc/treesitter.txt
index e35e145301..16de49029e 100644
--- a/runtime/doc/treesitter.txt
+++ b/runtime/doc/treesitter.txt
@@ -508,30 +508,21 @@ get_captures_at_pos({bufnr}, {row}, {col})
         table[] List of captures `{ capture = "capture name", metadata = { ...
         } }`
 
-get_node_at_cursor({winnr})              *vim.treesitter.get_node_at_cursor()*
-    Returns the smallest named node under the cursor
-
-    Parameters: ~
-      • {winnr}  (integer|nil) Window handle or 0 for current window (default)
-
-    Return: ~
-        (string) Name of node under the cursor
-
-                                            *vim.treesitter.get_node_at_pos()*
-get_node_at_pos({bufnr}, {row}, {col}, {opts})
+get_node({opts})                                   *vim.treesitter.get_node()*
     Returns the smallest named node at the given position
 
     Parameters: ~
-      • {bufnr}  (integer) Buffer number (0 for current buffer)
-      • {row}    (integer) Position row
-      • {col}    (integer) Position column
-      • {opts}   (table) Optional keyword arguments:
-                 • lang string|nil Parser language
-                 • ignore_injections boolean Ignore injected languages
-                   (default true)
+      • {opts}  (table|nil) Optional keyword arguments:
+                • bufnr integer|nil Buffer number (nil or 0 for current
+                  buffer)
+                • pos table|nil 0-indexed (row, col) tuple. Defaults to cursor
+                  position in the current window. Required if {bufnr} is not
+                  the current buffer
+                • ignore_injections boolean Ignore injected languages (default
+                  true)
 
     Return: ~
-        |TSNode||nil under the cursor
+        |TSNode| | nil Node at the given position
 
 get_node_range({node_or_range})              *vim.treesitter.get_node_range()*
     Returns the node's range or an unpacked range table
-- 
cgit