Add treesit-thing-settings

* lisp/treesit.el (treesit--things-around)
(treesit--navigate-thing)
(treesit-thing-at-point): Update docstring.
* src/treesit.c (treesit_traverse_validate_predicate): Refer to
treesit-thing-settings.
(syms_of_treesit): Add Vtreesit_thing_settings.

diff --git a/lisp/treesit.el b/lisp/treesit.el
index cb94d7feb94d3a4a45694946801c66e239599881..b03ab0484a800820725c8aeaf746a560941a024b 100644 (file)
--- a/lisp/treesit.el
+++ b/lisp/treesit.el
@@ -248,7 +248,7 @@ type as it.  If no such parent exists, return nil.
 
 If PRED is non-nil, match each parent's type with PRED rather
 than using NODE's type.  PRED can also be a predicate function,
-and more.  See `treesit-things-definition' for detail.
+and more.  See `treesit-thing-settings' for detail.
 
 If INCLUDE-NODE is non-nil, return NODE if it satisfies PRED."
   (let ((pred (or pred (rx-to-string
@@ -2062,7 +2062,7 @@ parent thing surrounding POS.  All of three could be nil if no
 sound things exists.
 
 PRED can be a regexp, a predicate function, and more.  See
-`treesit-things-definition' for details."
+`treesit-thing-settings' for details."
   (let* ((node (treesit-node-at pos))
          (result (list nil nil nil)))
     ;; 1. Find previous and next sibling defuns.
@@ -2152,7 +2152,7 @@ position it would move to.  If there aren't enough things to move
 across, return nil.
 
 PRED can be a regexp, a predicate function, and more.  See
-`treesit-things-definition' for detail.
+`treesit-thing-settings' for details.
 
 TACTIC determines how does this function move between things.  It
 can be `nested', `top-level', `restricted', or nil.  `nested'
@@ -2245,8 +2245,8 @@ function is called recursively."
   "Return the thing node at point or nil if none is found.
 
 \"Thing\" is defined by PRED, which can be a regexp, a
-predication function, and more, see `treesit-things-definition'
-for detail.
+predication function, and more, see `treesit-thing-settings'
+for details.
 
 Return the top-level defun if TACTIC is `top-level', return the
 immediate parent thing if TACTIC is `nested'."

diff --git a/src/treesit.c b/src/treesit.c
index b15a53236e4ae63042b18725dab3845543a40584..6117b2df59533e85a9c50ee093e1d16f60c043e3 100644 (file)
--- a/src/treesit.c
+++ b/src/treesit.c
@@ -3195,8 +3195,7 @@ treesit_traverse_validate_predicate (Lisp_Object pred,
       else if (STRINGP (car) && FUNCTIONP (cdr))
        return true;
     }
-  *signal_data = list2 (build_string ("Invalid predicate, see TODO for "
-                                     "valid forms of predicate"),
+  *signal_data = list2 (build_string ("Invalid predicate, see `treesit-thing-settings' for valid forms of predicate"),
                        pred);
   return false;
 }
@@ -3268,10 +3267,11 @@ treesit_traverse_match_predicate (TSTreeCursor *cursor, Lisp_Object pred,
   return false;
 }
 
-/* Traverse the parse tree starting from CURSOR.  See TODO for the
-   shapes PRED can have.  If the node satisfies PRED, leave CURSOR on
-   that node and return true.  If no node satisfies PRED, move CURSOR
-   back to starting position and return false.
+/* Traverse the parse tree starting from CURSOR.  See
+   `treesit-thing-settings' for the shapes PRED can have.  If the
+   node satisfies PRED, leave CURSOR on that node and return true.  If
+   no node satisfies PRED, move CURSOR back to starting position and
+   return false.
 
    LIMIT is the number of levels we descend in the tree.  FORWARD
    controls the direction in which we traverse the tree, true means
@@ -3791,7 +3791,8 @@ syms_of_treesit (void)
                "This parser is deleted and cannot be used",
                Qtreesit_error);
   define_error (Qtreesit_invalid_predicate,
-               "Invalid predicate, see TODO for valid forms for a predicate",
+               "Invalid predicate, see `treesit-thing-settings' "
+               "for valid forms for a predicate",
                Qtreesit_error);
 
   DEFVAR_LISP ("treesit-load-name-override-list",
@@ -3823,6 +3824,33 @@ then in the `tree-sitter' subdirectory of `user-emacs-directory', and
 then in the system default locations for dynamic libraries, in that order.  */);
   Vtreesit_extra_load_path = Qnil;
 
+  DEFVAR_LISP ("treesit-thing-settings",
+              Vtreesit_thing_settings,
+              doc:
+              /* A list defining things.
+
+The value should be an alist of (LANGUAGE . DEFINITIONS), where
+LANGUAGE is a language symbol, and DEFINITIONS is a list of
+
+    (THING PRED)
+
+THING is a symbol representing the thing, like `defun', `sexp', or
+`block'; PRED defines what kind of node can be qualified as THING.
+
+PRED can be a regexp string that matches the type of the node; it can
+be a predicate function that takes the node as the sole argument and
+returns t if the node is the thing; it can be a cons (REGEXP . FN),
+which is a combination of a regexp and a predicate function, and the
+node has to match both to qualify as the thing.
+
+PRED can also be recursively defined.  It can be (or PRED...), meaning
+satisfying anyone of the inner PREDs qualifies the node; or (not
+PRED), meaning not satisfying the inner PRED qualifies the node.
+
+Finally, PRED can refer to other THINGs defined in this list by using
+the symbol of that THING.  For example, (or block sexp).  */);
+  Vtreesit_thing_settings = Qnil;
+
   staticpro (&Vtreesit_str_libtree_sitter);
   Vtreesit_str_libtree_sitter = build_pure_c_string ("libtree-sitter-");
   staticpro (&Vtreesit_str_tree_sitter);