Inspecting

If your code works with a large number of nodes, consider using the traversal APIs, which are more efficient.

The result of parsing is a syntax tree of the entire source code (string, buffer). It contains syntax nodes that indicate the structure of the source code. Tree-sitter provides APIs to inspect and traverse this structure, but does not support modifying it directly (for the purposes of source code transformation or generation).

tsc-root-node tree
Get the root node of a syntax tree.
tsc-changed-ranges old-tree new-tree
Compare an edited old syntax tree to a newly parsed one. It is typically used in tree-sitter-after-change-functions hook. This function returns a sequence of ranges whose syntactic structure has changed. Each range is a vector in the form of [start-bytepos end-bytepos start-point end-point].

In tree-sitter’s context, point typically means a pair of (line-number . byte-column), instead of its usual meaning of current position. See Data Types.

tsc-tree-to-sexp
tsc-node-to-sexp
Debug utilities that return the sexp representation of a syntax tree/node, as a string.

Node Properties

Functions that return a node’s property have the prefix tsc-node-:

tsc-node-type
tsc-node-named-p
Tree-sitter’s parse tree is a concrete syntax tree, which contains nodes for every single token in the source code, including things which are typically omitted in a simpler abstract syntax tree, like commas, parentheses, punctuations, keywords.

These less important nodes are called anonymous nodes. Their node types are strings. For example: "if", "else". The more important nodes are call named nodes. Their node types are symbols, corresponding to the named rules that define them in the language’s grammar. For example: identifier, block, if_expression.

In Tree-sitter’s documentation, due to the low-level nature of C and JSON, node types are always represented as strings. Representing named node types as symbols makes it more Lisp-idiomatic, and is more consistent with tree queries.

tsc-node-extra-p
Whether a node is an extra node, which is not required by the grammar, but can appear anywhere in the source code, like comments.
tsc-node-error-p
Whether the node represents a syntax error. The node type of an error node is the special symbol ERROR.
tsc-node-has-error-p
Whether the node contains a syntax error.
tsc-node-missing-p
Whether a node is a missing node, i.e. inserted by the parser in order to recover from certain kinds of syntax errors, like a missing semicolon.
tsc-node-start-byte
tsc-node-end-byte
The start/end byte position of a node.
tsc-node-start-position
tsc-node-end-position
The start/end position of a node. These functions assume that the current buffer is the source buffer of the given node’s syntax tree.
tsc-node-range
A node’s [start-bytepos end-bytepos start-point end-point].

As described in the previous section, the -named- variants of the functions in this section allow working on the parse tree as if it is an abstract syntax tree.

tsc-get-parent node
Get a node’s parent node.
tsc-count-children node
tsc-count-named-children node
Count the number of child nodes (all, or named only).
tsc-get-nth-child node nth
tsc-get-nth-named-child node nth
Get a child node by its 0-based index (any, or named only). 
(let ((func (tree-sitter-node-at-pos 'function_item)))
  (tsc-get-nth-child func 0)        ; An "fn" node
  (tsc-get-nth-named-child func 0)) ; An 'identifier node
tsc-get-child-by-field node field
Certain node types assign unique field names to specific child nodes. This function allows retrieving child nodes by their field names, instead of by their indexes. The field name should be specified as a keyword. 
;; Get name of the current function definition.
(let ((func (tree-sitter-node-at-pos 'function_item)))
  (tsc-node-text (tsc-get-child-by-field func :name)))

In Tree-sitter’s documentation, due to the low-level nature of C and JSON, field names are specified as strings. Representing field names as keywords makes it more Lisp-idiomatic.

tsc-get-next-sibling node
tsc-get-prev-sibling node
tsc-get-next-named-sibling node
tsc-get-prev-named-sibling node
Get next/previous sibling node (any, or named only).
tsc-get-descendant-for-position-range node beg end
tsc-get-named-descendant-for-position-range node beg end
Get smallest descendant node that spans the given range. 
;; Get the syntax node the cursor is on.
(let ((p (point)))
  (tsc-get-descendant-for-position-range
   (tsc-root-node tree-sitter-tree) p p))