Next: Accessing Node Information, Previous: Using Tree-sitter Parser, Up: Parsing Program Source [Contents][Index]
Here’s some terminology 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 or equal to pos, and the node’s end position is greater 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 grammar
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 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 limit is
non-nil, it must be a number that limits the tree traversal to
that many levels down the tree. If limit 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 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 traverse leaf nodes first, then 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 return non-nil
if it matches.
For example, for a subtree on the left that consist 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, limit is
the number of levels to go down from root. If limit 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 the argument and should
return non-nil to indicate that the node should be kept. If
named is non-nil, this function only examines the named
nodes.
This function repeatedly finds the parents of node, and returns
the parent that satisfies predicate, a function that takes a
node as the argument. If no parent satisfies predicate, this
function returns nil.
This function repeatedly finds the parent of node, and keeps doing so as long as the nodes satisfy predicate, a function that takes a node as the argument. That is, this function returns the farthest parent that still satisfies predicate.
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.
Next: Accessing Node Information, Previous: Using Tree-sitter Parser, Up: Parsing Program Source [Contents][Index]