diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index e79c8cef180..b1bbe5e0a96 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1366,7 +1366,7 @@ Parsing Program Source * Language Definitions:: Loading tree-sitter language definitions. * Using Parser:: Introduction to parsers. -* Retrieving Node:: Retrieving node from syntax tree. +* Retrieving Nodes:: Retrieving nodes from a syntax tree. * Accessing Node Information:: Accessing node information. * Pattern Matching:: Pattern matching with query patterns. * Multiple Languages:: Parse text written in multiple languages. diff --git a/doc/lispref/parsing.texi b/doc/lispref/parsing.texi index f690e6a6047..2c838e317e5 100644 --- a/doc/lispref/parsing.texi +++ b/doc/lispref/parsing.texi @@ -41,7 +41,7 @@ source files that mix multiple programming languages. @menu * Language Definitions:: Loading tree-sitter language definitions. * Using Parser:: Introduction to parsers. -* Retrieving Node:: Retrieving node from syntax tree. +* Retrieving Nodes:: Retrieving nodes from a syntax tree. * Accessing Node Information:: Accessing node information. * Pattern Matching:: Pattern matching with query patterns. * Multiple Languages:: Parse text written in multiple languages. @@ -337,7 +337,8 @@ language definition. @item token(@var{rule}) marks @var{rule} to produce a single leaf node. That is, instead of generating a parent node with individual child nodes under it, -everything is combined into a single leaf node. +everything is combined into a single leaf node. @xref{Retrieving +Nodes}. @item token.immediate(@var{rule}) Normally, grammar rules ignore preceding whitespace; this changes @var{rule} to match only when there is no preceding @@ -461,8 +462,8 @@ This function parses @var{string} using @var{language}, and returns the root node of the generated syntax tree. @end defun -@node Retrieving Node -@section Retrieving Node +@node Retrieving Nodes +@section Retrieving Nodes @cindex retrieve node, tree-sitter @cindex tree-sitter, find node @cindex get node, tree-sitter @@ -487,28 +488,27 @@ Nodes are not automatically updated when the associated buffer is modified, and there is no way to update a node once it is retrieved. Using an outdated node signals the @code{treesit-node-outdated} error. -@heading Retrieving node from syntax tree +@heading Retrieving nodes from syntax tree @cindex retrieving tree-sitter nodes @cindex syntax tree, retrieving nodes +@cindex leaf node, of tree-sitter parse tree +@cindex tree-sitter parse tree, leaf node @defun treesit-node-at pos &optional parser-or-lang named -This function returns a @emph{leaf} node at buffer position @var{pos}. +This function returns a @dfn{leaf} node at buffer position @var{pos}. A leaf node is a node that doesn't have any child nodes. This function tries to return a node whose span covers @var{pos}: the -node's beginning is less or equal to @var{pos}, and the node's end is -greater or equal to @var{pos}. +node's beginning position is less or equal to @var{pos}, and the +node's end position is greater or equal to @var{pos}. -But if no leaf node's span covers @var{pos} (e.g., @var{pos} is on the +If no leaf node's span covers @var{pos} (e.g., @var{pos} is in the whitespace between two leaf nodes), this function returns the first leaf node after @var{pos}. Finally, if there is no leaf node after @var{pos}, return the first leaf node before @var{pos}. -If @var{pos} is in between two adjacent nodes, this function returns -the one after @var{pos}. - When @var{parser-or-lang} is @code{nil} or omitted, this function uses the first parser in @code{(treesit-parser-list)} of the current buffer. If @var{parser-or-lang} is a parser object, it uses that @@ -517,10 +517,10 @@ parser using that language in @code{(treesit-parser-list)}, and uses that. If this function cannot find a suitable node to return, it returns -nil. +@code{nil}. -If @var{named} is non-@code{nil}, this function looks for a named node -only (@pxref{tree-sitter named node, named node}). +If @var{named} is non-@code{nil}, this function looks only for named +nodes (@pxref{tree-sitter named node, named node}). Example: @@ -570,7 +570,7 @@ parser, it returns @code{nil}. Given a node, a Lisp program can retrieve other nodes starting from it, or query for information about this node. -@heading Retrieving node from other nodes +@heading Retrieving nodes from other nodes @cindex syntax tree nodes, retrieving from other nodes @subheading By kinship diff --git a/lisp/treesit.el b/lisp/treesit.el index 4d1a6bdf827..1070b66f704 100644 --- a/lisp/treesit.el +++ b/lisp/treesit.el @@ -173,8 +173,8 @@ parser in `treesit-parser-list', or nil if there is no parser." A leaf node is a node that doesn't have any child nodes. -The returned node's span covers POS: the node's beginning is less -or equal to POS, and the node's end is greater or equal to POS. +The returned node's span covers POS: the node's beginning is before +or at POS, and the node's end is at or after POS. If no leaf node's span covers POS (e.g., POS is on whitespace between two leaf nodes), return the first leaf node after POS. @@ -182,9 +182,6 @@ between two leaf nodes), return the first leaf node after POS. If there is no leaf node after POS, return the first leaf node before POS. -If POS is in between two adjacent nodes, return the one after -POS. - Return nil if no leaf node can be returned. If NAMED is non-nil, only look for named nodes.