From: Yuan Fu <casouri@gmail.com>
Date: Tue, 14 Jun 2022 21:30:39 +0000 (-0700)
Subject: Change treesit-check-query and mention it in documentation
X-Git-Tag: emacs-29.0.90~1912
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=a7288594f493a20664f1934a9fc760537caadcc3;p=emacs.git

Change treesit-check-query and mention it in documentation

* doc/lispref/parsing.texi (Pattern Matching): Mention it.
* lisp/treesit.el (treesit-check-query): Rename to
treesit-query-validate.
* src/treesit.c (Ftreesit_query_capture, Ftreesit_query_compile):
Mention it.
---

diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi
index 1c4a7805a31..36c03364e39 100644
--- a/doc/lispref/parsing.texi
+++ b/doc/lispref/parsing.texi
@@ -816,7 +816,7 @@ are both non-nil, it only pattern matches nodes in that range.
 @vindex treesit-query-error
 This function raise a @var{treesit-query-error} if @var{query} is
 malformed.  The signal data contains a description of the specific
-error.
+error.  You can use @code{treesit-query-validate} to debug the query.
 @end defun
 
 @defun treesit-query-in source query &optional beg end
@@ -1111,6 +1111,10 @@ a query is accepted.
 @defun treesit-query-compile language query
 This function compiles @var{query} for @var{language} into a compiled
 query object and returns it.
+
+This function raise a @var{treesit-query-error} if @var{query} is
+malformed.  The signal data contains a description of the specific
+error.  You can use @code{treesit-query-validate} to debug the query.
 @end defun
 
 @defun treesit-expand-query query
diff --git a/lisp/treesit.el b/lisp/treesit.el
index 09f750f9d52..ad90d9f9f01 100644
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -1038,10 +1038,11 @@ uses the first parser in `treesit-parser-list'."
           (remove '(:eval treesit--inspect-name)
                   mode-line-misc-info))))
 
-(defun treesit-check-query (query language)
+(defun treesit-query-validate (language query)
   "Check if QUERY is valid for LANGUAGE.
 If QUERY is invalid, display the query in a popup buffer, jumps
 to the offending pattern and highlight the pattern."
+  (cl-assert (or (consp query) (stringp query)))
   (let ((buf (get-buffer-create "*tree-sitter check query*")))
     (with-temp-buffer
       (treesit-get-parser-create language)
diff --git a/src/treesit.c b/src/treesit.c
index 5b344a2ea1c..df8c992bb5d 100644
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -1522,8 +1522,9 @@ DEFUN ("treesit-query-compile",
 Querying a compiled query is much faster than an uncompiled one.
 LANGUAGE is the language this query is for.
 
-Signals treesit-query-error if QUERY is malformed or something
-else goes wrong.  */)
+Signals treesit-query-error if QUERY is malformed or something else
+goes wrong.  You can use `treesit-query-validate' to debug the
+query.  */)
   (Lisp_Object language, Lisp_Object query)
 {
   if (!Ftreesit_query_p (query))
@@ -1564,8 +1565,9 @@ compile your queries if it will be used over and over.
 BEG and END, if both non-nil, specifies the range in which the query
 is executed.
 
-Raise an treesit-query-error if QUERY is malformed, or something
-else goes wrong.  */)
+Signals treesit-query-error if QUERY is malformed or something else
+goes wrong.  You can use `treesit-query-validate' to debug the
+query.  */)
   (Lisp_Object node, Lisp_Object query,
    Lisp_Object beg, Lisp_Object end)
 {