This section covers some general guidelines on developing tree-sitter integration for a major mode.
A major mode supporting tree-sitter features should roughly follow this pattern:
(define-derived-mode woomy-mode prog-mode "Woomy" "A mode for Woomy programming language." (when (treesit-ready-p 'woomy) (setq-local treesit-variables ...) ... (treesit-major-mode-setup)))
treesit-ready-p automatically emits a warning if conditions for
enabling tree-sitter aren’t met.
If a tree-sitter major mode shares setup with its “native” counterpart, one can create a “base mode” that contains the common setup, like this:
(define-derived-mode woomy--base-mode prog-mode "Woomy" "An internal mode for Woomy programming language." (common-setup) ...)
(define-derived-mode woomy-mode woomy--base-mode "Woomy" "A mode for Woomy programming language." (native-setup) ...)
(define-derived-mode woomy-ts-mode woomy--base-mode "Woomy" "A mode for Woomy programming language." (when (treesit-ready-p 'woomy) (setq-local treesit-variables ...) ... (treesit-major-mode-setup)))
This function checks for conditions for activating tree-sitter. It checks whether Emacs was built with tree-sitter, whether the buffer’s size is not too large for tree-sitter to handle, and whether the grammar for language is available on the system (see Tree-sitter Language Grammar).
This function emits a warning if tree-sitter cannot be activated. If
message, the warning is turned into a message;
if quiet is
t, no warning or message is displayed.
If all the necessary conditions are met, this function returns
nil; otherwise it returns
This function activates some tree-sitter features for a major mode.
Currently, it sets up the following features:
treesit-font-lock-settings(see Parser-based Font Lock) is non-
nil, it sets up fontification.
treesit-simple-indent-rules(see Parser-based Indentation) is non-
nil, it sets up indentation.
nil, it sets up navigation functions for
nil, it sets up add-log functions used by
treesit-simple-imenu-settings(see Imenu) is non-
nil, it sets up Imenu.
For supporting mixing of multiple languages in a major mode, see Parsing Text in Multiple Languages.
provides some additional functions for working with defuns:
treesit-defun-at-point returns the defun node at point, and
treesit-defun-name returns the name of a defun node.
This function returns the defun node at point, or
nil if none
is found. It respects
treesit-defun-tactic: if its value is
top-level, this function returns the top-level defun, and if
its value is
nested, it returns the immediate enclosing defun.
This function requires
treesit-defun-type-regexp to work. If
nil, this function simply returns
This function returns the defun name of node. It returns
nil if there is no defun name for node, or if node
is not a defun node, or if node is
Depending on the language and major mode, the defun names are names like function name, class name, struct name, etc.
nil, this function
nil, this variable’s value should be a function that is
called with a node as its argument, and returns the defun name of the
node. The function should have the same semantics as
treesit-defun-name: if the node is not a defun node, or the
node is a defun node but doesn’t have a name, or the node is
nil, it should return