;;; 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
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
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))
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
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,
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.
(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
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
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
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)
"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
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);
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);
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)
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);
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.
= 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
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. */
projects / emacs.git / commitdiff