; Fix documentation of recent treesit changes
* src/treesit.c (Ftreesit_query_capture) (Ftreesit_parser_embed_level, Ftreesit_parser_set_embed_level) (Ftreesit_parser_set_parent_node): * lisp/treesit.el (treesit-query-range) (treesit-query-range-by-language, treesit-range-settings) (treesit-range-rules, treesit--parser-at-level) (treesit--update-ranges-non-local, treesit--update-ranges-local) (treesit--update-range-1): Fix wording and typos in doc strings. * doc/lispref/parsing.texi (Pattern Matching): Fix wording.
This commit is contained in:
Eli Zaretskii
parent
becdfb11a5
commit
6ed119d305
4 changed files with 39 additions and 36 deletions
|
|
@ -1247,9 +1247,8 @@ matching node whose span overlaps with the region between @var{beg}
|
|||
and @var{end} is captured; it doesn't have to be completely contained
|
||||
in the region.
|
||||
|
||||
If @var{grouped} is non-@code{nil}, instead of returning a list of
|
||||
@w{@code{(@var{capture_name} . @var{node})}}, this function returns a
|
||||
list of list of it. The grouping is determined by @var{query}.
|
||||
If @var{grouped} is non-@code{nil}, this function returns a grouped list
|
||||
of lists of captured nodes. The grouping is determined by @var{query}.
|
||||
Captures in the same match of a pattern in @var{query} are grouped
|
||||
together.
|
||||
|
||||
|
|
|
|||
|
|
@ -153,7 +153,7 @@ of max unsigned 32-bit value for byte offsets into buffer text."
|
|||
|
||||
;;; Parser API supplement
|
||||
|
||||
;; The primary parser will be access frequently (after each re-parse,
|
||||
;; The primary parser will be accessed frequently (after each re-parse,
|
||||
;; before redisplay, etc, see
|
||||
;; `treesit--font-lock-mark-ranges-to-fontify'), so we don't want to
|
||||
;; allow it to be a callback function which returns the primary parser
|
||||
|
|
@ -559,8 +559,8 @@ respective offset values are added to each (START . END) range
|
|||
being returned. Capture names generally don't matter, but names
|
||||
that starts with an underscore are ignored.
|
||||
|
||||
RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
|
||||
returns the ranges to use for that node."
|
||||
RANGE-FN, if non-nil, is a function that takes a NODE and OFFSET, and
|
||||
returns the ranges to use for that NODE."
|
||||
(let ((offset-left (or (car offset) 0))
|
||||
(offset-right (or (cdr offset) 0)))
|
||||
(cl-loop for capture
|
||||
|
|
@ -585,8 +585,8 @@ Query NODE with QUERY, the captured nodes generates ranges. Nodes
|
|||
captured by the `@language' capture name are converted to language
|
||||
symbols with LANGUAGE-FN.
|
||||
|
||||
RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
|
||||
returns the ranges to use for that node.
|
||||
RANGE-FN, if non-nil, is a function that takes a NODE and OFFSET, and
|
||||
returns the ranges to use for that NODE.
|
||||
|
||||
BEG, END, OFFSET are the same as in `treesit-query-range'."
|
||||
(let ((offset-left (or (car offset) 0))
|
||||
|
|
@ -644,13 +644,13 @@ using a single parser for all the ranges. If OFFSET is non-nil, it
|
|||
should be a cons of numbers (START-OFFSET . END-OFFSET), where the start
|
||||
and end offset are added to each queried range to get the result ranges.
|
||||
|
||||
If RANGE-FN is non-nil, it should be a function, Emacs uses this
|
||||
If RANGE-FN is non-nil, it should be a function; Emacs uses this
|
||||
function to compute the ranges to use for the embedded parser. The
|
||||
function is passed the captured node and OFFSET, and should return a
|
||||
list of ranges, where each range is a cons of the start and end
|
||||
position.
|
||||
|
||||
Capture names generally don't matter, but names that starts with
|
||||
Capture names generally don't matter, but names that start with
|
||||
an underscore are ignored.
|
||||
|
||||
QUERY can also be a function, in which case it is called with 2
|
||||
|
|
@ -672,8 +672,8 @@ like this:
|
|||
Each QUERY is a tree-sitter query in either the string,
|
||||
s-expression or compiled form.
|
||||
|
||||
Capture names generally don't matter, but names that starts with an
|
||||
underscore are ignored. And `@language' is reserved.
|
||||
Capture names generally don't matter, but names that start with an
|
||||
underscore are ignored. The `@language' capture name is reserved.
|
||||
|
||||
For each QUERY, :KEYWORD and VALUE pairs add meta information to
|
||||
it. For example,
|
||||
|
|
@ -690,8 +690,8 @@ this way: Emacs queries QUERY in the host language's parser,
|
|||
computes the ranges spanned by the captured nodes, and applies
|
||||
these ranges to parsers for the embedded language.
|
||||
|
||||
If the embed language is dynamic, then a function in place of the embed
|
||||
language symbol. This function will by passed a node and should return
|
||||
If the embed language is dynamic, then `:embed' can specify a
|
||||
function. This function will by passed a node and should return
|
||||
the language symbol for the embedded code block. The node is the one
|
||||
captured from QUERY with capture name `@language'. Also make sure the
|
||||
code block and language capture are in the same match group.
|
||||
|
|
@ -896,10 +896,10 @@ it."
|
|||
(delete-overlay ov)))))
|
||||
|
||||
(defsubst treesit--parser-at-level (parsers level &optional include-null)
|
||||
"Filter for parsers in PARSERS that has embed level equal to LEVEL.
|
||||
"Filter for parsers in PARSERS that have embed level equal to LEVEL.
|
||||
|
||||
If INCLUDE-NULL is non-nil, also include parsers that has a nil embed
|
||||
level."
|
||||
If INCLUDE-NULL is non-nil, also include parsers whose embed level
|
||||
is nil."
|
||||
(seq-filter (lambda (parser)
|
||||
(or (eq (treesit-parser-embed-level parser) level)
|
||||
(and include-null
|
||||
|
|
@ -918,7 +918,7 @@ Use QUERY to get the ranges, and set ranges for embedded parsers to
|
|||
those ranges. HOST-PARSER and QUERY must match.
|
||||
|
||||
EMBED-LANG is either a language symbol or a function that takes a node
|
||||
and return a language symbol.
|
||||
and returns a language symbol.
|
||||
|
||||
EMBED-LEVEL is the embed level for the local parsers being created or
|
||||
updated. When looking for existing local parsers, only look for parsers
|
||||
|
|
@ -928,7 +928,7 @@ level.
|
|||
RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
|
||||
returns the ranges to use for that node.
|
||||
|
||||
Return updated parsers in a list."
|
||||
Return updated parsers as a list."
|
||||
(let ((ranges-by-lang
|
||||
(if (functionp embed-lang)
|
||||
(treesit-query-range-by-language
|
||||
|
|
@ -998,7 +998,7 @@ for the local parser.
|
|||
RANGE-FN, if non-nil, is a function that takes a node and OFFSET, and
|
||||
returns the ranges to use for that node.
|
||||
|
||||
Return the created local parsers in a list."
|
||||
Return the created local parsers as a list."
|
||||
;; Update range.
|
||||
(let ((ranges-by-lang
|
||||
(if (functionp embedded-lang)
|
||||
|
|
@ -1050,8 +1050,8 @@ Return the created local parsers in a list."
|
|||
"Given a HOST-PARSER, update ranges between BEG and END.
|
||||
|
||||
Go over each settings in SETTINGS, try to create or update the embedded
|
||||
language in that setting. Return the created or updated embedded
|
||||
language parsers in a list.
|
||||
language in that setting. Return the list of the created or updated
|
||||
embedded language parsers.
|
||||
|
||||
EMBED-LEVEL is the embed level for the embedded parser being created or
|
||||
updated. When looking for existing embedded parsers, only look for
|
||||
|
|
|
|||
|
|
@ -1827,8 +1827,8 @@ DEFUN ("treesit-parser-embed-level",
|
|||
|
||||
The embed level can be either nil or a non-negative integer. A value of
|
||||
nil means the parser isn't part of the embedded parser tree. The
|
||||
primary parser has embed level 0, from it, each layer of embedded parser
|
||||
has +1 embed level. */)
|
||||
primary parser has embed level 0, and each additional layer of parser
|
||||
embedding increments the embed level by 1. */)
|
||||
(Lisp_Object parser)
|
||||
{
|
||||
treesit_check_parser (parser);
|
||||
|
|
@ -1839,7 +1839,9 @@ has +1 embed level. */)
|
|||
DEFUN ("treesit-parser-set-embed-level",
|
||||
Ftreesit_parser_set_embed_level, Streesit_parser_set_embed_level,
|
||||
2, 2, 0,
|
||||
doc: /* Set the embed level for PARSER to LEVEL. */)
|
||||
doc: /* Set the embed level for PARSER to LEVEL.
|
||||
LEVEL can be nil, for a parser that is not part of an embedded parser
|
||||
tree; otherwise it must be a non-negative integer. */)
|
||||
(Lisp_Object parser, Lisp_Object level)
|
||||
{
|
||||
treesit_check_parser (parser);
|
||||
|
|
@ -1859,7 +1861,7 @@ DEFUN ("treesit-parser-parent-node",
|
|||
1, 1, 0,
|
||||
doc: /* Return PARSER's parent node, if one exists.
|
||||
|
||||
Only embeded local parser can have parent node. When Emacs uses a node
|
||||
Only embeded local parsers can have parent node. When Emacs uses a node
|
||||
in the host parser to create this local parser, that node is considered
|
||||
the parent node of the local parser. */)
|
||||
(Lisp_Object parser)
|
||||
|
|
@ -1871,7 +1873,7 @@ the parent node of the local parser. */)
|
|||
DEFUN ("treesit-parser-set-parent-node",
|
||||
Ftreesit_parser_set_parent_node, Streesit_parser_set_parent_node,
|
||||
2, 2, 0,
|
||||
doc: /* Return PARSER's parent node to NODE. */)
|
||||
doc: /* Make NODE be the parent node of PARSER. */)
|
||||
(Lisp_Object parser, Lisp_Object node)
|
||||
{
|
||||
treesit_check_parser (parser);
|
||||
|
|
@ -3289,8 +3291,9 @@ in which the query is executed. Any matching node whose span overlaps
|
|||
with the region between BEG and END are captured, it doesn't have to
|
||||
be completely in the region.
|
||||
|
||||
If GROUPED is non-nil, group captures into matches and return a list of
|
||||
MATCH, where each MATH is a list of (CAPTURE_NAME . NODE).
|
||||
If GROUPED is non-nil, ther function groups the returned list of
|
||||
captures into matches and return a list of MATCH, where each MATCH is
|
||||
a list of the form (CAPTURE_NAME . NODE).
|
||||
|
||||
If NODE-ONLY is non-nil, return nodes only, and don't include
|
||||
CAPTURE_NAME.
|
||||
|
|
|
|||
|
|
@ -64,12 +64,13 @@ struct Lisp_TS_Parser
|
|||
= 0, end_byte = UINT32_MAX). */
|
||||
Lisp_Object last_set_ranges;
|
||||
/* Parsers for embedded code blocks will have a non-zero embed level.
|
||||
The primary parser has level 0, and each layer of embedded parser
|
||||
gets +1 level. The embed level can be either a non-negative
|
||||
integer or nil. Every parser created by treesit-parser-create
|
||||
starts with a nil level. If the value is nil, that means the range
|
||||
functions (treesit-update-ranges and friends) haven't touched this
|
||||
parser yet, and this parser isn't part of the embed parser tree. */
|
||||
The primary parser has level 0, and each additional layer of parser
|
||||
embedding increments the leve by 1. The embed level can be either
|
||||
a non-negative integer or nil. Every parser created by
|
||||
'treesit-parser-create' starts with a nil level. If the value is
|
||||
nil, that means the range functions (treesit-update-ranges and
|
||||
friends) haven't touched this parser yet, and this parser isn't
|
||||
part of the embed parser tree. */
|
||||
Lisp_Object embed_level;
|
||||
/* Some comments: Technically you could calculate embed_level by
|
||||
following parent_node, but parent_node might be outdated so it's a
|
||||
|
|
@ -80,7 +81,7 @@ struct Lisp_TS_Parser
|
|||
for a parser will be useful beyond this. And we can always convert
|
||||
these to properties later, but not vice versa. */
|
||||
/* When an embedded parser is created, it's usually based on a node in
|
||||
the host parser. This field saves that node so it possible to
|
||||
the host parser. This field saves that node so it's possible to
|
||||
climb up and out of the embedded parser into the host parser. Note
|
||||
that the range of the embedded parser doesn't have to match that of
|
||||
the parent node. */
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue