Here are some terms and conventions we use when documenting tree-sitter functions.
A node in a syntax tree spans some portion of the program text in the buffer. We say that a node is “smaller” or “larger” than another if it spans, respectively, a smaller or larger portion of buffer text than the other node. Since nodes that are deeper (“lower”) in the tree are children of the nodes that are “higher” in the tree, it follows that a lower node will always be smaller than a node that is higher in the node hierarchy. A node that is higher up in the syntax tree contains one or more smaller nodes as its children, and therefore spans a larger portion of buffer text.
When a function cannot find a node, it returns nil. For
convenience, all functions that take a node as argument and return
a node, also accept the node argument of nil and in that case
just return nil.
Nodes are not automatically updated when the associated buffer is
modified, and there is no way to update a node once it is retrieved.
Using an outdated node signals the treesit-node-outdated error.
This function returns a leaf node at buffer position pos. A leaf node is a node that doesn’t have any child nodes.
This function tries to return a node whose span covers pos: the node’s beginning position is less than or equal to pos, and the node’s end position is greater than or equal to pos.
If no leaf node’s span covers pos (e.g., pos is in the whitespace between two leaf nodes), this function returns the first leaf node after pos.
Finally, if there is no leaf node after pos, return the first leaf node before pos.
If parser-or-lang is a parser object, this function uses that
parser; if parser-or-lang is a language, this function uses the
first parser for that language in the current buffer, or creates one
if none exists; if parser-or-lang is nil, this function
tries to guess the language at pos by calling
treesit-language-at (see Parsing Text in Multiple Languages).
If this function cannot find a suitable node to return, it returns
nil.
If named is non-nil, this function looks only for named
nodes (see named node).
Example:
;; Find the node at point in a C parser's syntax tree. (treesit-node-at (point) 'c) ⇒ #<treesit-node (primitive_type) in 23-27>
This function returns the smallest node that covers the region of buffer text between beg and end. In other words, the start of the node is before or at beg, and the end of the node is at or after end.
Beware: calling this function on an empty line that is not
inside any top-level construct (function definition, etc.) most
probably will give you the root node, because the root node is the
smallest node that covers that empty line. Most of the time, you want
to use treesit-node-at instead.
If parser-or-lang is a parser object, this function uses that
parser; if parser-or-lang is a language, this function uses the
first parser for that language in the current buffer, or creates one
if none exists; if parser-or-lang is nil, this function
tries to guess the language at beg by calling
treesit-language-at.
If named is non-nil, this function looks for a named node
only (see named node).
This function returns the root node of the syntax tree generated by parser.
This function finds the first parser for language in the current
buffer, or creates one if none exists, and returns the root node
generated by that parser. If language is omitted, it uses the
first parser in the parser list. If it cannot find an appropriate
parser, it returns nil.
Given a node, a Lisp program can retrieve other nodes starting from it, or query for information about this node.
This function returns the immediate parent of node.
If node is more than 1000 levels deep in a parse tree, the
return value is undefined. Currently it returns nil, but that
could change in the future.
This function returns the n’th child of node. If
named is non-nil, it counts only named nodes
(see named node).
For example, in a node that represents a string "text", there
are three children nodes: the opening quote ", the string text
text, and the closing quote ". Among these nodes, the
first child is the opening quote ", and the first named child
is the string text.
This function returns nil if there is no n’th child.
n could be negative, e.g., −1 represents the last child.
This function returns all of node’s children as a list. If
named is non-nil, it retrieves only named nodes.
This function finds the next sibling of node. If named is
non-nil, it finds the next named sibling.
This function finds the previous sibling of node. If
named is non-nil, it finds the previous named sibling.
To make the syntax tree easier to analyze, many language grammars
assign field names to child nodes (see field name). For example, a function_definition node
could have a declarator node and a body node.
This function finds the child of node whose field name is field-name, a string.
;; Get the child that has "body" as its field name. (treesit-node-child-by-field-name node "body") ⇒ #<treesit-node (compound_statement) in 45-89>
This function finds the first child of node that extends beyond
buffer position pos. “Extends beyond” means the end of the
child node is greater or equal to pos. This function only looks
for immediate children of node, and doesn’t look in its
grandchildren. If named is non-nil, it looks for the
first named child (see named node).
This function finds the smallest descendant node of node
that spans the region of text between positions beg and
end. It is similar to treesit-node-at. If named
is non-nil, it looks for the smallest named child.
This function traverses the subtree of node (including
node itself), looking for a node for which predicate
returns non-nil. predicate is a regexp that is matched
against each node’s type, or a predicate function that takes a node
and returns non-nil if the node matches. The function returns
the first node that matches, or nil if none does.
By default, this function only traverses named nodes, but if all
is non-nil, it traverses all the nodes. If backward is
non-nil, it traverses backwards (i.e., it visits the last child
first when traversing down the tree). If depth is
non-nil, it must be a number that limits the tree traversal to
that many levels down the tree. If depth is nil, it
defaults to 1000.
Like treesit-search-subtree, this function also traverses the
parse tree and matches each node with predicate (except for
start), where predicate can be a regexp or a function.
For a tree like the one below where start is marked ‘S’,
this function traverses 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 traverses leaf nodes first, before moving upwards.
Like treesit-search-subtree, this function only searches for
named nodes by default, but if all is non-nil, it
searches for all nodes. If backward is non-nil, it
searches backwards.
While treesit-search-subtree traverses the subtree of a node,
this function starts with node start and traverses every node
that comes after it in the buffer position order, i.e., nodes with
start positions greater than the end position of start.
In the tree shown above, treesit-search-subtree traverses node
‘S’ (start) and nodes marked with o, where this
function traverses the nodes marked with numbers. This function is
useful for answering questions like “what is the first node after
start in the buffer that satisfies some condition?”
This function moves point to the start or end of the next node after
node in the buffer that matches predicate. If start
is non-nil, stop at the beginning rather than the end of a node.
This function guarantees that the matched node it returns makes progress in terms of buffer position: the start/end position of the returned node is always greater than that of node.
Arguments predicate, backward, and all are the same
as in treesit-search-forward.
This function creates a sparse tree from root’s subtree.
It takes the subtree under root, and combs it so only the nodes
that match predicate are left. Like previous functions, the
predicate can be a regexp string that matches against each
node’s type, or a function that takes a node and returns
non-nil if it matches.
For example, given the subtree on the left that consists of both numbers and letters, if predicate is “letter only”, the returned tree is the one on the right.
a a a
| | |
+---+---+ +---+---+ +---+---+
| | | | | | | | |
b 1 2 b | | b c d
| | => | | => |
c +--+ c + e
| | | | |
+--+ d 4 +--+ d
| | |
e 5 e
If process-fn is non-nil, instead of returning the
matched nodes, this function passes each node to process-fn and
uses the returned value instead. If non-nil, depth
limits the number of levels to go down from root. If
depth is nil, it defaults to 1000.
Each node in the returned tree looks like
(tree-sitter-node . (child …)). The
tree-sitter-node of the root of this tree will be nil if
root doesn’t match predicate. If no node matches
predicate, the function returns nil.
This function finds immediate children of node that satisfy predicate.
The predicate function takes a node as argument and should
return non-nil to indicate that the node should be kept. If
named is non-nil, this function only examines named
nodes.
This function repeatedly finds the parents of node, and returns
the parent that satisfies pred, a function that takes a node as
argument and returns a boolean that indicates a match. If no parent
satisfies pred, this function returns nil.
Normally this function only looks at the parents of node but not
node itself. But if include-node is non-nil, this
function returns node if node satisfies pred.
This function goes up the tree starting from node, and keeps doing so as long as the nodes satisfy pred, a function that takes a node as argument. That is, this function returns the highest parent of node that still satisfies pred. Note that if node satisfies pred but its immediate parent doesn’t, node itself is returned.
This function returns the highest parent of node that has the
same type as node. If no such parent exists, it returns
nil. Therefore this function is also useful for testing
whether node is top-level.
If type is non-nil, this function matches each parent’s
type with type as a regexp, rather than using node’s type.