Add manual entry for tree-sitter search functions

* doc/lispref/parsing.texi (Retrieving Node): New subsection
"Searching for node".
* doc/lispref/positions.texi (List Motion): Add entries for
treesit-defun-query, treesit-beginning-of-defun, treesit-end-of-defun.
* lisp/treesit.el (treesit-search-forward, treesit-search-beginning)
(treesit-search-end): Minor docstring fix-up.

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 917779f78a3405aee60056bce93087d3a74b9113..6d5c7b8dc20628e4a51f9e438bd7b2d20b6fe282 100644 (file)
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -591,6 +591,38 @@ that spans the range from @var{beg} to @var{end}.  It is similar to
 for named child (@pxref{tree-sitter named node, named node}).
 @end defun
 
+@heading Searching for node
+
+@defun treesit-search-beginning query arg &optional lang up-only
+This function searches for the next node that @var{query} captures,
+starting at point.  Use the parser in current buffer that has
+@var{lang} as its language, if @var{lang} is nil, use the first parser
+in current buffer’s buffer list.
+
+This function stops at the @var{arg}'th match.  If @var{arg} is
+negative, search backward.  If the search succeeds, stop at the
+beginning of the matched node and return the node.  Return nil if
+search failed.
+
+By default, this function searches by traversing the parse tree depth
+first, starting from the node at point.  If @var{up-only} is non-nil,
+this function only go to siblings and parents, but never go down into
+children nodes.
+@end defun
+
+@defun treesit-search-end query arg &optional lang up-only
+This function is like @code{treesit-search-beginning}, but stops at
+the end of the matched node.
+@end defun
+
+@defun treesit-search-forward pos-fn arg query &optional lang up-only
+This function is like @code{treesit-search-beginning} and
+@code{treesit-search-end}, but instead of stopping at the beginning or
+end of the matched node, it determines where to stop by @var{pos-fn},
+where @var{pos-fn} is a function that takes a node and returns a
+position
+@end defun
+
 @heading More convenient functions
 
 @defun treesit-filter-child node pred &optional named

diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi
index 7945232bf8f01f8916349632661ae2095e8dfde0..809ac207d24a58b6511f12359bab9fb5f986827e 100644 (file)
--- a/doc/lispref/positions.texi
+++ b/doc/lispref/positions.texi
@@ -834,6 +834,32 @@ a defun.  The function @code{end-of-defun} calls this function instead
 of using its normal method.
 @end defvar
 
+When tree-sitter support is available (@pxref{Parsing Program
+Source}), Emacs can find the beginning and end of a function according
+to the syntax tree.
+
+@defvar treesit-defun-query
+Set this variable to a tree-sitter query that matches defun
+definitions, then @code{treesit-beginning-of-defun} and
+@code{treesit-end-of-defun} can find the beginning and end of a defun.
+
+Make sure to use a compiled query for this variable, otherwise
+@code{treesit-beginning-of-defun} and @code{treesit-end-of-defun} will
+be very slow.
+@end defvar
+
+@defun treesit-beginning-of-defun &optional arg
+This function finds the beginning of a defun according to
+@var{treesit-defun-query}.  This function is suitable for the value of
+@var{beginning-of-defun-function}.
+@end defun
+
+@defun treesit-end-of-defun &optional arg
+This function finds the end of a defun according to
+@var{treesit-defun-query}.  This function is suitable for the value of
+@var{end-of-defun-function}.
+@end defun
+
 @node Skipping Characters
 @subsection Skipping Characters
 @cindex skipping characters

diff --git a/lisp/treesit.el b/lisp/treesit.el
index b969f185148db6fea672fa1f071379ac1f16e36e..9c66f32ec27f79b87e5943c43cfb296d191858f7 100644 (file)
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -862,9 +862,6 @@ indentation (target) is in green, current indentation is in red."
 (defun treesit-search-forward (pos-fn arg query &optional lang up-only)
   "Search forward for nodes that matches QUERY from current point.
 
-This is a more primitive function, you might want to use
-`treesit-search-beginning' or `treesit-search-end' instead.
-
 QUERY has to capture the node to match.  LANG specifies the
 language in which we search for nodes.  If LANG is nil, use the
 first parser in (`treesit-parser-list').
@@ -875,7 +872,7 @@ negative ARG means go backward.
 POS-FN can be either `treesit-node-start' or `treesit-node-end',
 or any function that takes a node and returns a position.
 
-If search succeeds, stop at the position returned by POS-FN and
+If the search succeeds, stop at the position returned by POS-FN and
 return the matched node.  Return nil if search failed.
 
 We search by traversing the parse tree, visiting every node
@@ -925,12 +922,12 @@ Stops at the beginning of matched node.
 
 QUERY has to capture the node to match.  LANG specifies the
 language in which we search for nodes.  If LANG is nil, use the
-first parser in (`treesit-parser-list').
+first parser in current buffer's parser list.
 
 Move forward/backward ARG times, positive ARG means go forward,
 negative ARG means go backward.
 
-If search succeeds, return the matched node.  Return nil if
+If the search succeeds, return the matched node.  Return nil if
 search failed.
 
 We search by traversing the parse tree, visiting every node
@@ -953,7 +950,7 @@ first parser in (`treesit-parser-list').
 Move forward/backward ARG times, positive ARG means go forward,
 negative ARG means go backward.
 
-If search succeeds, return the matched node.  Return nil if
+If the search succeeds, return the matched node.  Return nil if
 search failed.
 
 We search by traversing the parse tree, visiting every node