---

24.6.10 Parser-based Font Lock

Besides simple syntactic font lock and regexp-based font lock, Emacs also provides complete syntactic font lock with the help of a parser, currently provided by the tree-sitter library (see Parsing Program Source).

Function: treesit-font-lock-enable ¶

This function enables parser-based font lock in the current buffer.

Parser-based font lock and other font lock mechanism are not mutually exclusive. By default, if enabled, parser-based font lock runs first, then the simple syntactic font lock (if enabled), then regexp-based font lock.

Although parser-based font lock doesn’t share the same customization variables with regexp-based font lock, parser-based font lock uses similar customization schemes. The tree-sitter counterpart of font-lock-keywords is treesit-font-lock-settings.

Function: treesit-font-lock-rules :keyword value query... ¶

This function is used to set treesit-font-lock-settings. It takes care of compiling queries and other post-processing and outputs a value that treesit-font-lock-settings accepts. An example:

(treesit-font-lock-rules
 :language 'javascript
 :override t
 '((true) @font-lock-constant-face
   (false) @font-lock-constant-face)
 :language 'html
 "(script_element) @font-lock-builtin-face")

This function takes a list of text or s-exp queries. Before each query, there are :keyword and value pairs that configure that query. The :lang keyword sets the query’s language and every query must specify the language. Other keywords are optional:

Keyword	Value	Description
:override	nil	If the region already has a face, discard the new face
	t	Always apply the new face
	append	Append the new face to existing ones
	prepend	Prepend the new face to existing ones
	keep	Fill-in regions without an existing face

Capture names in query should be face names like font-lock-keyword-face. The captured node will be fontified with that face. Capture names can also be function names, in which case the function is called with (start end node), where start and end are the start and end position of the node in buffer, and node is the node itself. If a capture name is both a face and a function, the face takes priority. If a capture name is not a face name nor a function name, it is ignored.

Variable: treesit-font-lock-settings ¶

A list of settings for tree-sitter font lock. The exact format of this variable is considered internal. One should always use treesit-font-lock-rules to set this variable.

Each setting is of form

(language query)

Each setting controls one parser (often of different language). And language is the language symbol (see Tree-sitter Language Definitions); query is the query (see Pattern Matching Tree-sitter Nodes).

Multi-language major modes should provide range functions in treesit-range-functions, and Emacs will set the ranges accordingly before fontifing a region (see Parsing Text in Multiple Languages).