Function: treesit-search-forward

treesit-search-forward is a function defined in treesit.c.

Signature

(treesit-search-forward START PREDICATE &optional BACKWARD ALL)

Documentation

Search for node matching PREDICATE in the parse tree of START.

Start traversing the tree from node START, and match PREDICATE with each node (except START itself) along the way. PREDICATE is a regexp string that matches against each node's type, or a function that takes a node and returns non-nil if it matches.

By default, only search for named nodes, but if ALL is non-nil, search for all nodes. If BACKWARD is non-nil, search backwards.

Return the first matched node, or nil if none matches.

For a tree like below, where START is marked by S, traverse as numbered from 1 to 12:

                12
                |
       S--------3----------11
       | | |
  o--o-+--o 1--+--2 6--+-----10
  | | | |
  o o +-+-+ +--+--+
                      | | | | |
                      4 5 7 8 9

Note that this function doesn't traverse the subtree of START, and it always traverse leaf nodes first, then upwards.

Other relevant functions are documented in the treesit group.

View in manual

Shortdoc

;; treesit
(treesit-search-forward node "function_definition")
    e.g. => #<treesit-node (function_definition) in 57-146>

Source Code

// Defined in /usr/src/emacs/src/treesit.c
{
  CHECK_TS_NODE (start);
  CHECK_TYPE (STRINGP (predicate) || FUNCTIONP (predicate),
	      list3 (Qor, Qstringp, Qfunctionp), predicate);
  CHECK_SYMBOL (all);
  CHECK_SYMBOL (backward);

  treesit_initialize ();

  Lisp_Object parser = XTS_NODE (start)->parser;
  Lisp_Object return_value = Qnil;
  TSTreeCursor cursor;
  if (!treesit_cursor_helper (&cursor, XTS_NODE (start)->node, parser))
    return return_value;

  specpdl_ref count = SPECPDL_INDEX ();
  record_unwind_protect_ptr (treesit_traverse_cleanup_cursor, &cursor);

  if (treesit_search_forward (&cursor, predicate, parser,
			      NILP (backward), NILP (all)))
    {
      TSNode node = ts_tree_cursor_current_node (&cursor);
      return_value = make_treesit_node (parser, node);
    }

  return unbind_to (count, return_value);
}