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.
We talk about a node being “smaller” or “larger”, and “lower” or “higher”. A smaller and lower node is lower in the syntax tree and therefore spans a smaller portion of buffer text; a larger and higher node is higher up in the syntax tree, it contains many smaller nodes as its children, and therefore spans a larger portion of 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 the smallest node that starts at or after the buffer position pos. In other words, the start of the node is greater or equal to pos.
When parser-or-lang is nil or omitted, this function uses
the first parser in (treesit-parser-list) of the current
buffer. If parser-or-lang is a parser object, it uses that
parser; if parser-or-lang is a language, it finds the first
parser using that language in (treesit-parser-list), and uses
that.
If named is non-nil, this function looks for a named node
only (see named node).
When pos is after all the text in the buffer, technically there
is no node after pos. But for convenience, this function will
return the last leaf node in the parse tree. If strict is
non-nil, this function will strictly comply to the semantics and
return nil.
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, described above, instead.
When parser-or-lang is nil, this function uses the first
parser in (treesit-parser-list) of the current buffer. If
parser-or-lang is a parser object, it uses that parser; if
parser-or-lang is a language, it finds the first parser using
that language in (treesit-parser-list), and uses that.
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 that uses language in
(treesit-parser-list) of the current buffer, and returns the
root node generated by that parser. 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.
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 definitions
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-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.
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.
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]