37.4 Accessing Node Information

Basic information of Node

Every node is associated with a parser, and that parser is associated with a buffer. The following functions retrieve them.

Function: treesit-node-parser node

This function returns node’s associated parser.

Function: treesit-node-buffer node

This function returns node’s parser’s associated buffer.

Function: treesit-node-language node

This function returns node’s parser’s associated language.

Each node represents a portion of text in the buffer. Functions below find relevant information about that text.

Function: treesit-node-start node

Return the start position of node.

Function: treesit-node-end node

Return the end position of node.

Function: treesit-node-text node &optional object

Return the buffer text that node represents, as a string. (If node is retrieved from parsing a string, it will be the text from that string.)

Here are some predicates on tree-sitter nodes:

Function: treesit-node-p object

Checks if object is a tree-sitter syntax node.

Function: treesit-node-eq node1 node2

Checks if node1 and node2 refer to the same node in a tree-sitter syntax tree. This function uses the same equivalence metric as equal. You can also compare nodes using equal (see Equality Predicates).

Property information

In general, nodes in a concrete syntax tree fall into two categories: named nodes and anonymous nodes. Whether a node is named or anonymous is determined by the language grammar (see named node).

Apart from being named or anonymous, a node can have other properties. A node can be “missing”: such nodes are inserted by the parser in order to recover from certain kinds of syntax errors, i.e., something should probably be there according to the grammar, but is not there. This can happen during editing of the program source, when the source is not yet in its final form.

A node can be “extra”: such nodes represent things like comments, which can appear anywhere in the text.

A node can be “outdated”, if its parser has reparsed at least once after the node was created.

A node “has error” if the text it spans contains a syntax error. It can be that the node itself has an error, or one of its descendants has an error.

A node is considered live if its parser is not deleted, and the buffer to which it belongs is a live buffer (see Killing Buffers).

Function: treesit-node-check node property

This function returns non-nil if node has the specified property. property can be named, missing, extra, outdated, has-error, or live.

Function: treesit-node-type node

Named nodes have “types” (see node type). For example, a named node can be a string_literal node, where string_literal is its type. The type of an anonymous node is just the text that the node represents; e.g., the type of a ‘,’ node is just ‘,’.

This function returns node’s type as a string.

Information as a child or parent

Function: treesit-node-index node &optional named

This function returns the index of node as a child node of its parent. If named is non-nil, it only counts named nodes (see named node).

Function: treesit-node-field-name node

A child of a parent node could have a field name (see field name). This function returns the field name of node as a child of its parent.

Function: treesit-node-field-name-for-child node n

This function returns the field name of the n’th child of node. It returns nil if there is no n’th child, or the n’th child doesn’t have a field name.

Note that n counts both named and anonymous children, and n can be negative, e.g., −1 represents the last child.

Function: treesit-node-child-count node &optional named

This function returns the number of children of node. If named is non-nil, it only counts named children (see named node).