From bb8a46e559ec39437a1524b3e9746746768effcc Mon Sep 17 00:00:00 2001 From: Yuan Fu Date: Thu, 13 Oct 2022 15:08:20 -0700 Subject: [PATCH] Update tree-sitter manual to reflect the previous commit * doc/lispref/modes.texi: Update manual to reflect previous change: remove :toggle and :level, add :feature. Document new variables and functions. * doc/lispref/parsing.texi: Add the missing closing bracket in @code{(t . nil)}. --- doc/lispref/modes.texi | 75 ++++++++++++++++++++++++++++++---------- doc/lispref/parsing.texi | 6 ++-- 2 files changed, 60 insertions(+), 21 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index b1287c6ad05..ed232556b28 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3911,10 +3911,12 @@ a value that @var{treesit-font-lock-settings} accepts. An example: @group (treesit-font-lock-rules :language 'javascript + :feature 'constant :override t '((true) @@font-lock-constant-face (false) @@font-lock-constant-face) :language 'html + :feature 'script "(script_element) @@font-lock-builtin-face") @end group @end example @@ -3922,7 +3924,12 @@ a value that @var{treesit-font-lock-settings} accepts. An example: This function takes a list of text or s-exp queries. Before each query, there are @var{:keyword} and @var{value} pairs that configure that query. The @code{:lang} keyword sets the query’s language and -every query must specify the language. Other keywords are optional: +every query must specify the language. The @code{:feature} keyword +sets the feature name of the query. Users can control which features +are enabled with @code{font-lock-maximum-decoration} and +@code{treesit-font-lock-feature-list} (see below). + +Other keywords are optional: @multitable @columnfractions .15 .15 .6 @headitem Keyword @tab Value @tab Description @@ -3932,21 +3939,8 @@ every query must specify the language. Other keywords are optional: @item @tab @code{append} @tab Append the new face to existing ones @item @tab @code{prepend} @tab Prepend the new face to existing ones @item @tab @code{keep} @tab Fill-in regions without an existing face -@item @code{:toggle} @tab @var{symbol} @tab -If non-nil, its value should be a variable name. The variable's value -(nil/non-nil) disables/enables the query during fontification. -@item @tab nil @tab Always enable this query. -@item @code{:level} @tab @var{integer} @tab -If non-nil, its value should be the decoration level for this query. -Decoration level is controlled by @code{font-lock-maximum-decoration}. -@item @tab nil @tab Always enable this query. @end multitable -Note that a query is applied only when both @code{:toggle} and -@code{:level} permit it. @code{:level} is used for global, -coarse-grained control, whereas @code{:toggle} is for local, -fine-grained control. - Capture names in @var{query} should be face names like @code{font-lock-keyword-face}. The captured node will be fontified with that face. Capture names can also be function names, in which @@ -3957,6 +3951,42 @@ 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. @end defun +@defvar treesit-font-lock-feature-list +This is a list of lists of feature symbols. + +Each sublist represents a decoration level. +@code{font-lock-maximum-decoration} controls which levels are +activated. + +Inside each sublist are feature symbols, which corresponds to the +@code{:feature} value of a query defined in +@code{treesit-font-lock-rules}. Removing a feature symbol from this +list disables the corresponding query during font-lock. + +Common feature names (for general programming language) include +function-name, type, variable-name (LHS of assignments), builtin, +constant, keyword, string-interpolation, comment, doc, string, +operator, preprocessor, escape-sequence, key (in key-value +pairs). Major modes are free to subdivide or extend on these +common features. + +For example, the value of this variable could be: +@example +@group +((comment string doc) ; level 1 + (function-name keyword type builtin constant) ; level 2 + (variable-name string-interpolation key)) ; level 3 +@end group +@end example + +Major modes should set this variable before calling +@code{treesit-font-lock-enable}. + +@findex treesit-font-lock-recompute-features +In addition, for further changes to this variable to take effect, run +@code{treesit-font-lock-recompute-features}. +@end defvar + @defvar treesit-font-lock-settings A list of @var{setting}s for tree-sitter font lock. The exact format of this variable is considered internal. One should always use @@ -3965,12 +3995,21 @@ of this variable is considered internal. One should always use Each @var{setting} is of form @example -(@var{language} @var{query}) +(@var{query} @var{enable} @var{feature} @var{override}) @end example -Each @var{setting} controls one parser (often of different language). -And @var{language} is the language symbol (@pxref{Language -Definitions}); @var{query} is the query (@pxref{Pattern Matching}). +@var{query} must be a compiled query (@pxref{Pattern Matching}). + +For @var{setting} to be activated for font-lock, @var{enable} must be +t. To disable this @var{setting}, set @var{enable} to nil. + +@var{feature} is the ``feature name'' of the query, users can control +which features are enabled with @code{font-lock-maximum-decoration} +and @code{treesit-font-lock-feature-list}. + +@var{override} is the override flag for this query. Its value can be +t, nil, append, prepend, keep. See more in +@code{treesit-font-lock-rules}. @end defvar Multi-language major modes should provide range functions in diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index 8b684d11fcd..d2a333027b9 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -87,9 +87,9 @@ library. This function returns non-nil if @var{language} exists and is loadable. -If @var{detail} is non-nil, return @code{(t . nil) when @var{language} -is available, @code{(nil . DATA)} when unavailable. @var{data} is the -signal data of @code{treesit-load-language-error}. +If @var{detail} is non-nil, return @code{(t . nil)} when +@var{language} is available, @code{(nil . DATA)} when unavailable. +@var{data} is the signal data of @code{treesit-load-language-error}. @end defun @vindex treesit-load-name-override-list -- 2.39.2