From: Eli Zaretskii Date: Fri, 28 Feb 2025 07:12:05 +0000 (+0200) Subject: ; Fix documentation of recent treesit changes X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6f0473c646ddcc0c79a053ca56c97f18cbd86e1f;p=emacs.git ; 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. (cherry picked from commit 6ed119d3052ffebd20450ec0c7fb3abf863b3a49) --- diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index 2b224036de0..ade7b819756 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -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. diff --git a/lisp/treesit.el b/lisp/treesit.el index 190d05a5926..725c2037a69 100644 --- a/lisp/treesit.el +++ b/lisp/treesit.el @@ -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. @@ -895,10 +895,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 @@ -917,7 +917,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 @@ -927,7 +927,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 @@ -997,7 +997,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) @@ -1049,8 +1049,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 diff --git a/src/treesit.c b/src/treesit.c index c8af17a5b8b..20c3626732a 100644 --- a/src/treesit.c +++ b/src/treesit.c @@ -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. diff --git a/src/treesit.h b/src/treesit.h index d19a0e76216..d4cfc47ee5d 100644 --- a/src/treesit.h +++ b/src/treesit.h @@ -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. */