Currently, Emacs uses the tree-sitter library (@pxref{Parsing Program
Source}) for this purpose.
-@defun treesit-font-lock-enable
-This function enables parser-based font lock in the current buffer.
-@end defun
-
Parser-based font lock and other font lock mechanisms are not mutually
exclusive. By default, if enabled, parser-based font lock runs first,
then the syntactic font lock (if enabled), then the regexp-based
For more information about queries, patterns, and capture names, see
@ref{Pattern Matching}.
+To setup tree-sitter fontification, a major mode should first set
+@code{treesit-font-lock-settings} with the output of
+@code{treesit-font-lock-rules}, then call
+@code{treesit-major-mode-setup}.
+
@defun treesit-font-lock-rules :keyword value query...
This function is used to set @var{treesit-font-lock-settings}. It
takes care of compiling queries and other post-processing, and outputs
@end example
Major modes should set this variable before calling
-@code{treesit-font-lock-enable}.
+@code{treesit-major-mode-setup}.
@findex treesit-font-lock-recompute-features
For this variable to take effect, a Lisp program should call
@code{treesit-font-lock-recompute-features} (which resets
-@code{treesit-font-lock-settings} accordingly).
+@code{treesit-font-lock-settings} accordingly), or
+@code{treesit-major-mode-setup} (which calls
+@code{treesit-font-lock-recompute-features}).
@end defvar
@defvar treesit-font-lock-settings
below: then the major mode needs only to write some indentation rules
and the engine takes care of the rest.
-To enable the parser-based indentation engine, set the value of
+To enable the parser-based indentation engine, either set
+@var{treesit-simple-indent-rules} and call
+@code{treesit-major-mode-setup}, or equivalently, set the value of
@code{indent-line-function} to @code{treesit-indent}.
@defvar treesit-indent-function
@cindex major mode, developing with tree-sitter
This section covers some general guidelines on developing tree-sitter
-integration for a major mode. For tree-sitter integration with
-specific Emacs features, see @ref{Parser-based Font Lock}, and see
-@ref{Parser-based Indentation}.
-
-@findex treesit-mode
-@findex global-treesit-mode
-Emacs provides @code{treesit-mode} and @code{global-treesit-mode}.
-When one of these two modes is turned on, major modes should turn on
-their tree-sitter support, if they have one. Major modes works with
-@code{treesit-mode} by setting @code{major-mode-backend-function}.
-
-@defvar major-mode-backend-function
-This is a buffer-local variable that holds a function.
-@code{treesit-mode} uses this function to turn on/off tree-sitter
-support.
-
-This function is passed two arguments: @var{backend} and @var{warn}.
-@var{backend} is a symbol representing the backend we want to
-activate. Currently it can be @code{treesit} or @code{elisp}.
-
-If @var{warn} is non-@code{nil}, display a warning if a @code{backend}
-can't activated; if @var{warn} is @code{nil}, just print a message
-and don't display any warning.
-@end defvar
+integration for a major mode.
+
+In general, a major mode supporting tree-sitter features should
+roughly follow this pattern:
+
+@example
+@group
+(define-derived-mode woomy-mode prog-mode "Woomy"
+ "A mode for Woomy programming language."
+ ;; Shared setup.
+ ...
+ (cond
+ ;; Tree-sitter setup.
+ ((treesit-ready-p 'woomy-mode 'woomy)
+ (setq-local treesit-variables ...)
+ (treesit-major-mode-setup))
+ ;; Non-tree-sitter setup.
+ (t
+ ...)))
+@end group
+@end example
+
+First, the major mode should use @code{treesit-ready-p} to determine
+whether the user wants to activate tree-sitter features for the mode,
+and whether tree-sitter can be activated in this mode.
+
+@defun treesit-ready-p mode language &optional quiet
+This function checks for conditions for activating tree-sitter. It
+checks whether the users turns tree-sitter on for @var{mode}
+(according to @code{treesit-settings}), whether tree-sitter is built
+with Emacs, the buffer's size, and whether @var{languag} is available.
+
+When user sets @var{mode} to @var{demand} in @code{treesit-settings},
+this function emits a warning if tree-sitter cannot be activated. If
+@var{quiet} is @code{message}, the warning is turned into a message,
+if @var{quiet} is @code{nil}, no warning or message is displayed.
-@defun treesit-ready-p warn &rest languages
-This is a convenience function that checks for conditions for
-activating tree-sitter. It checks for whether tree-sitter is built
-with Emacs, the buffer's size, and whether each @var{language} is
-available.
+If @var{mode} is nil, this function doesn't check user's preference in
+@code{treesit-settings}.
-If all conditions are met, it returns non-@code{nil}. If not, it
-shows a warning or displays a message depending on the value of
-@var{warn}. If @var{warn} is non-@code{nil}, show a warning,
-otherwise display an echo-area message.
+If all conditions are met, this function returns non-@code{nil}.
+Otherwise it return @code{nil}.
+@end defun
+
+Then, the major mode should setup tree-sitter variables, and call
+@code{treesit-major-mode-setup}.
+
+@defun treesit-major-mode-setup
+This function activates some tree-sitter features for a major mode.
+
+Currently, it sets up the following features:
+@itemize
+@item
+If @code{treesit-font-lock-settings} is non-@code{nil}, it sets up
+fontification.
+@item
+If @code{treesit-simple-indent-rules} is non-@code{nil}, it sets up
+indentation.
+@item
+If @code{treesit-defun-type-regexp} is non-@code{nil}, it sets up
+navigation functions for @code{beginning-of-defun} and
+@code{end-of-defun}.
+@end itemize
@end defun
+For more information of these built-in tree-sitter features,
+@pxref{Parser-based Font Lock}, @pxref{Parser-based Indentation}, and
+@pxref{List Motion}.
@node Tree-sitter C API
@section Tree-sitter C API Correspondence
of using its normal method.
@end defvar
+@findex treesit-beginning-of-defun
+@findex treesit-end-of-defun
+If Emacs is compiled with tree-sitter, it can use the parsed
+information to move across syntax constructs. A major mode can set
+@code{treesit-defun-type-regexp} and get navigation functionality for
+free, by using @code{treesit-beginning-of-defun} and
+@code{treesit-end-of-defun}.
+
+@defvar treesit-defun-type-regexp
+This is a regexp matching the node type of defun nodes. (For
+``node'', ``node type'', @pxref{Parsing Program Source}.)
+
+For example, @code{python-mode} sets this variable to a regexp that
+matches either @code{function_definition} or @code{class_definition}.
+@end defvar
+
@node Skipping Characters
@subsection Skipping Characters
@cindex skipping characters
projects / emacs.git / commitdiff