From 29418f954eb114bf3c108b6e03569036f854ae45 Mon Sep 17 00:00:00 2001 From: Yuan Fu Date: Tue, 8 Nov 2022 10:39:53 -0800 Subject: [PATCH] ; Improve tree-sitter documentation * doc/lispref/modes.texi (Parser-based Font Lock) * doc/lispref/parsing.texi (Multiple Languages) * lisp/treesit.el (treesit-range-rules) (treesit-font-lock-rules): Improve phrasing around queries and keyword and values. --- doc/lispref/modes.texi | 22 +++++++++++----------- doc/lispref/parsing.texi | 12 ++++++------ lisp/treesit.el | 15 +++++++++------ 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 8a0b5a12a10..da190b0b02e 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -3950,16 +3950,16 @@ example: @end group @end example -This function takes a series of @var{query-spec}s, which are triplets -@w{@code{@var{:keyword} @var{value} @dots{} @var{query}}}. Each -@var{query} is a tree-sitter query in either the string, s-expression -or compiled form. - -The @var{:keyword} and @var{value} pairs configure the query which -follows them in the argument list. The @code{:lang} keyword sets the -query's 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 +This function takes a series of @var{query-spec}s, where each +@var{query-spec} is a @var{query} preceded by multiple pairs of +@var{:keyword} and @var{value}. Each @var{query} is a tree-sitter +query in either the string, s-expression or compiled form. + +For each @var{query}, the @var{:keyword} and @var{value} pairs add +meta information to it. The @code{:lang} keyword declares +@var{query}'s language. The @code{:feature} keyword sets the feature +name of @var{query}. Users can control which features are enabled +with @code{font-lock-maximum-decoration} and @code{treesit-font-lock-feature-list} (described below). These two keywords are mandated. @@ -3975,7 +3975,7 @@ Other keywords are optional: @item @tab @code{keep} @tab Fill-in regions without an existing face @end multitable -Lisp programs mark patterns in the query with capture names (names +Lisp programs mark patterns in @var{query} with capture names (names that starts with @code{@@}), and tree-sitter will return matched nodes tagged with those same capture names. For the purpose of fontification, capture names in @var{query} should be face names like diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index a22b088111d..cae83f8d5cc 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -1537,14 +1537,14 @@ takes care of compiling queries and other post-processing, and outputs a value that @var{treesit-range-settings} can have. It takes a series of @var{query-spec}s, where each @var{query-spec} is -a triplet of arguments @w{@code{@var{:keyword} @var{value} @dots{} -@var{query}}}. Each @var{query} is a tree-sitter query in either the +a @var{query} preceded by zero or more pairs of @var{keyword} and +@var{value}. Each @var{query} is a tree-sitter query in either the string, s-expression or compiled form, or a function. -If @var{query} is a tree-sitter query, it should be used with the pair -@var{:keyword} and @var{value}, where the @code{:embed} -keyword specifies the embedded language, and the @code{:host} -keyword specified the host language. +If @var{query} is a tree-sitter query, it should be preceeded by two +@var{:keyword} @var{value} pairs, where the @code{:embed} keyword +specifies the embedded language, and the @code{:host} keyword +specified the host language. @code{treesit-update-ranges} uses @var{query} to figure out how to set the ranges for parsers for the embedded language. It queries diff --git a/lisp/treesit.el b/lisp/treesit.el index 61bca49d8ca..c2a15835b3b 100644 --- a/lisp/treesit.el +++ b/lisp/treesit.el @@ -374,15 +374,17 @@ to change. Use `treesit-range-rules' to set this variable.") (defun treesit-range-rules (&rest query-specs) "Produce settings for `treesit-range-settings'. -QUERY-SPECS are a series of QUERY-SPEC triplets of the form +QUERY-SPECS are a series of QUERY-SPECs, where each QUERY-SPEC is +a QUERY preceeded by zero or more pairs of :KEYWORD and VALUE, +like this: :KEYWORD VALUE... QUERY Each QUERY is a tree-sitter query in either the string, s-expression or compiled form. -Each QUERY should be preceded by :KEYWORD VALUE pairs that -configures this query. For example, +For each QUERY, :KEYWORD and VALUE pairs add meta information to +it. For example, (treesit-range-rules :embed \\='javascript @@ -562,7 +564,8 @@ t, nil, append, prepend, keep. See more in (defun treesit-font-lock-rules (&rest query-specs) "Return a value suitable for `treesit-font-lock-settings'. -QUERY-SPECS is a series of 3 arguments: +QUERY-SPECS is a series of QUERY-SPECs. Each QUERY-SPEC is a +QUERY preceded by multiple pairs of :KEYWORD and VALUE: :KEYWORD VALUE... QUERY @@ -570,8 +573,8 @@ QUERY is a tree-sitter query in either the string, s-expression or compiled form. For each query, captured nodes are highlighted with the capture name as its face. -Before each QUERY there could be :KEYWORD and VALUE pairs that -configure the query (and only that query). For example, +:KEYWORD and VALUE pairs preceeding a QUERY add meta information +to QUERY. For example, (treesit-font-lock-rules :language \\='javascript -- 2.39.5