---

37.2 Using Tree-sitter Parser

This section describes how to create and configure a tree-sitter parser. In Emacs, each tree-sitter parser is associated with a buffer. As the user edits the buffer, the associated parser and syntax tree are automatically kept up-to-date.

Variable: treesit-max-buffer-size ¶

This variable contains the maximum size of buffers in which tree-sitter can be activated. Major modes should check this value when deciding whether to enable tree-sitter features.

Function: treesit-can-enable-p ¶

This function checks whether the current buffer is suitable for activating tree-sitter features. It basically checks treesit-available-p and treesit-max-buffer-size.

Function: treesit-parser-create language &optional buffer no-reuse ¶

Create a parser for the specified buffer and language (see Tree-sitter Language Definitions). If buffer is omitted or nil, it stands for the current buffer.

By default, this function reuses a parser if one already exists for language in buffer, but if no-reuse is non-nil, this function always creates a new parser.

Given a parser, we can query information about it.

Function: treesit-parser-buffer parser ¶

This function returns the buffer associated with parser.

Function: treesit-parser-language parser ¶

This function returns the language used by parser.

Function: treesit-parser-p object ¶

This function checks if object is a tree-sitter parser, and returns non-nil if it is, and nil otherwise.

There is no need to explicitly parse a buffer, because parsing is done automatically and lazily. A parser only parses when a Lisp program queries for a node in its syntax tree. Therefore, when a parser is first created, it doesn’t parse the buffer; it waits until the Lisp program queries for a node for the first time. Similarly, when some change is made in the buffer, a parser doesn’t re-parse immediately.

When a parser does parse, it checks for the size of the buffer. Tree-sitter can only handle buffer no larger than about 4GB. If the size exceeds that, Emacs signals the treesit-buffer-too-large error with signal data being the buffer size.

Once a parser is created, Emacs automatically adds it to the internal parser list. Every time a change is made to the buffer, Emacs updates parsers in this list so they can update their syntax tree incrementally.

Function: treesit-parser-list &optional buffer ¶

This function returns the parser list of buffer. If buffer is nil or omitted, it defaults to the current buffer.

Function: treesit-parser-delete parser ¶

This function deletes parser.

Normally, a parser “sees” the whole buffer, but when the buffer is narrowed (see Narrowing), the parser will only see the accessible portion of the buffer. As far as the parser can tell, the hidden region was deleted. When the buffer is later widened, the parser thinks text is inserted at the beginning and at the end. Although parsers respect narrowing, modes should not use narrowing as a means to handle a multi-language buffer; instead, set the ranges in which the parser should operate. See Parsing Text in Multiple Languages.

Because a parser parses lazily, when the user or a Lisp program narrows the buffer, the parser is not affected immediately; as long as the mode doesn’t query for a node while the buffer is narrowed, the parser is oblivious of the narrowing.

Besides creating a parser for a buffer, a Lisp program can also parse a string. Unlike a buffer, parsing a string is a one-off operation, and there is no way to update the result.

Function: treesit-parse-string string language ¶

This function parses string using language, and returns the root node of the generated syntax tree.