procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

; More documentation improvements for treesit

Browse source 
* lisp/treesit.el (treesit-language-at, treesit-range-rules)
(treesit-font-lock-rules): Doc fixes.

* doc/lispref/parsing.texi (Multiple Languages):
* doc/lispref/modes.texi (Parser-based Font Lock): Fix wording.
This commit is contained in:
Eli Zaretskii 2022-11-06 11:59:27 +02:00
parent 9fbbb23552
commit 488a6efe32
3 changed files with 50 additions and 49 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
doc/lispref/modes.texi
View file

@ -3950,15 +3950,15 @@ example:
@end group
@end example
This function takes a list of @var{query-spec}s of the form
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.
Before each query, there are @var{:keyword} @var{value} pairs that
configure that query. 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
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
@code{treesit-font-lock-feature-list} (described below). These two
keywords are mandated.

71
doc/lispref/parsing.texi
View file

@ -1336,7 +1336,8 @@ Lisp programs should call @code{treesit-update-ranges} to make sure
the ranges for each parser are correct before using parsers in a
buffer, and call @code{treesit-language-at} to figure out the language
responsible for the text at some position. Multi-language major modes
sets @code{treesit-range-settings} and
set @code{treesit-range-settings} and
@c FIXME: ``power''?
@code{treesit-language-at-point-function} respectively to power these
two functions. These functions and variables are explained in more
detail towards the end of the section.
@ -1417,9 +1418,9 @@ Like other query functions, this function raises the
@code{treesit-query-error} error if @var{query} is malformed.
@end defun
@heading Supporting multiple languages as Lisp programs
@heading Supporting multiple languages in Lisp programs
It should suffice for general Lisp programs to call these two
It should suffice for general Lisp programs to call the following two
functions in order to support program sources that mixes multiple
languages.
@ -1430,8 +1431,8 @@ according to @code{treesit-range-settings}. If omitted, @var{beg}
defaults to the beginning of the buffer, and @var{end} defaults to the
end of the buffer.
For example, fontification functions uses this function before
querying for nodes in a region.
For example, fontification functions use this function before querying
for nodes in a region.
@end defun
@defun treesit-language-at pos
@ -1444,26 +1445,25 @@ value of @code{treesit-parser-list}. If there is no parser in the
buffer, it returns @code{nil}.
@end defun
@heading Supporting multiple languages as major modes
@heading Supporting multiple languages in major modes
@cindex host language, tree-sitter
@cindex tree-sitter host language
@cindex tree-sitter host and embedded languages
@cindex embedded language, tree-sitter
@cindex tree-sitter embedded language
Normally, in a set of languages that can be mixed together, there is a
host language and one or more embedded languages. A Lisp program
usually first parses the whole document with the host language's
parser, retrieve some information, sets ranges for the embedded
languages with that information, and then parses the embedded
@dfn{host language} and one or more @dfn{embedded languages}. A Lisp
program usually first parses the whole document with the host
language's parser, retrieves some information, sets ranges for the
embedded languages with that information, and then parses the embedded
languages.
Take a buffer containing @acronym{HTML}, @acronym{CSS} and JavaScript
as an example. A lisp program will first parse the whole buffer with
as an example. A Lisp program will first parse the whole buffer with
an @acronym{HTML} parser, then query the parser for
@code{style_element} and @code{script_element} nodes, which
corresponds to @acronym{CSS} and JavaScript text, respectively. Then
correspond to @acronym{CSS} and JavaScript text, respectively. Then
it sets the range of the @acronym{CSS} and JavaScript parser to the
range in which their corresponding nodes span.
ranges in which their corresponding nodes span.
Given a simple @acronym{HTML} document:
@ -1476,7 +1476,8 @@ Given a simple @acronym{HTML} document:
@end group
@end example
A Lisp program will first parse with a @acronym{HTML} parser, then set
@noindent
a Lisp program will first parse with a @acronym{HTML} parser, then set
ranges for @acronym{CSS} and JavaScript parsers:
@example
@ -1508,11 +1509,11 @@ ranges for @acronym{CSS} and JavaScript parsers:
Emacs automates this process in @code{treesit-update-ranges}. A
multi-language major mode should set @code{treesit-range-settings} so
that this function knows how to perform this process automatically.
Major modes should use the helper function @code{treesit-range-rules}
to generate the value that @code{treesit-range-settings} can have.
The settings in the following example directly translates to
operations shown above.
that @code{treesit-update-ranges} knows how to perform this process
automatically. Major modes should use the helper function
@code{treesit-range-rules} to generate a value that can be assigned to
@code{treesit-range-settings}. The settings in the following example
directly translate into operations shown above.
@example
@group
@ -1536,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
of the form @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, or a function.
a triplet of arguments @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, or a function.
If @var{query} is a tree-sitter qurey, it should be preceded by 2
pairs of @var{:keyword} and @var{value}, where the @code{:embed}
keyword specifies the @dfn{embedded language}, and the @code{:host}
keyword specified the @dfn{host language}.
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.
@code{treesit-update-ranges} uses @var{query} to figure out how to set
the ranges for parsers for the embedded language. It queries
@ -1551,7 +1552,7 @@ the ranges for parsers for the embedded language. It queries
the captured nodes span, and applies these ranges to embedded
language parsers.
If @var{query} is a function, it doesn't need any @var{keyword} and
If @var{query} is a function, it doesn't need any @var{:keyword} and
@var{value} pair. It should be a function that takes 2 arguments,
@var{start} and @var{end}, and sets the ranges for parsers in the
current buffer in the region between @var{start} and @var{end}. It is
@ -1560,11 +1561,11 @@ encompasses the region between @var{start} and @var{end}.
@end defun
@defvar treesit-range-settings
This variable helps @code{treesit-update-ranges} to update ranges for
parsers in the buffer. It is a list of @var{setting}s where the exact
format of a @var{setting} is considered internal. You should use
@code{treesit-range-rules} to generate a value that this variable can
have.
This variable helps @code{treesit-update-ranges} in updating the
ranges for parsers in the buffer. It is a list of @var{setting}s
where the exact format of a @var{setting} is considered internal. You
should use @code{treesit-range-rules} to generate a value that this
variable can have.
@c Because the format is internal, we don't document them here. Though
@c we do have it explained in the docstring. We also expose the fact
@ -1616,7 +1617,7 @@ This function checks for conditions for activating tree-sitter. It
checks whether the user turned on tree-sitter for @var{mode}
(according to @code{treesit-settings}), whether Emacs was built with
tree-sitter, whether the buffer's size is not too large for
tree-sitter to handle it, and whether language definition for
tree-sitter to handle it, and whether the language definition for
@var{language} is available on the system (@pxref{Language
Definitions}).

18
lisp/treesit.el
View file

@ -147,10 +147,10 @@ The function is called with one argument, the position of point.")
(defun treesit-language-at (position)
"Return the language at POSITION.
Assumes parser ranges are up-to-date. Returns the return value
of `treesit-language-at-point-function' if it's non-nil,
otherwise return the language of the first parser in
`treesit-parser-list', or nil if there is no parser."
This function assumes that parser ranges are up-to-date. It
returns the return value of `treesit-language-at-point-function'
if it's non-nil, otherwise it returns the language of the first
parser in `treesit-parser-list', or nil if there is no parser."
(if treesit-language-at-point-function
(funcall treesit-language-at-point-function position)
(when-let ((parser (car (treesit-parser-list))))
@ -374,7 +374,7 @@ 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 contains a series of QUERY-SPEC of the form
QUERY-SPECS are a series of QUERY-SPEC triplets of the form
:KEYWORD VALUE... QUERY
@ -396,8 +396,8 @@ computes the ranges spanned by the captured nodes, and applies
these ranges to parsers for the embedded language.
QUERY can also be a function that takes two arguments, START and
END. If QUERY is a function, it doesn't need :KEYWORD VALUE
pairs preceding it. This function should set the ranges for
END. If QUERY is a function, it doesn't need the :KEYWORD VALUE
pair preceding it. This function should set the ranges for
parsers in the current buffer in the region between START and
END. It is OK for this function to set ranges in a larger region
that encompasses the region between START and END."
@ -562,7 +562,7 @@ 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 made of a series of QUERY-SPECs of the form
QUERY-SPECS is a series of 3 arguments:
:KEYWORD VALUE... QUERY
@ -570,7 +570,7 @@ 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 VALUE pairs that
Before each QUERY there could be :KEYWORD and VALUE pairs that
configure the query (and only that query). For example,
(treesit-font-lock-rules