From baacad1771e3551ffdb1b88c41224fa1957e766c Mon Sep 17 00:00:00 2001 From: Yuan Fu Date: Sat, 29 Oct 2022 13:51:45 -0700 Subject: [PATCH] Reflect recent change in tree-sitter manual sections * doc/lispref/modes.texi (Parser-based Font Lock): treesit-font-lock-enable is replaced by treesit-major-mode-setup. * doc/lispref/modes.texi (Parser-based Indentation): Mention treesit-major-mode-setup, * doc/lispref/parsing.texi (Tree-sitter major modes): Remove treesit-mode and global-treesit-mode, explain setup guideline. --- doc/lispref/modes.texi | 19 +++++--- doc/lispref/parsing.texi | 97 +++++++++++++++++++++++++------------- doc/lispref/positions.texi | 16 +++++++ 3 files changed, 92 insertions(+), 40 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 6212c7cd87f..614bbe1293c 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3890,10 +3890,6 @@ also provides complete syntactic font lock with the help of a parser. 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 @@ -3930,6 +3926,11 @@ would be highlighted in @code{font-lock-keyword} face. 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 @@ -4012,12 +4013,14 @@ For example, the value of this variable could be: @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 @@ -4771,7 +4774,9 @@ It is more convenient to use the simple indentation engine described 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 diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index 903f3aa6a5f..fe51222e9bc 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -1505,43 +1505,74 @@ to write query patterns, @pxref{Pattern Matching}. @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 diff --git a/doc/lispref/positions.texi b/doc/lispref/positions.texi index 7945232bf8f..0c56ece185b 100644 --- a/doc/lispref/positions.texi +++ b/doc/lispref/positions.texi @@ -834,6 +834,22 @@ a defun. The function @code{end-of-defun} calls this function instead 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 -- 2.39.2