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

Fix recent changes in documentation

Browse source 
* lisp/treesit.el (treesit-node-at): Doc fix.

* doc/lispref/parsing.texi (Language Definitions): Add
cross-reference.
(Retrieving Nodes): Renamed from "Retrieving Node"; all references
changed.
(Retrieving Nodes): Fix wording and markup.
This commit is contained in:
Eli Zaretskii 2022-11-12 10:57:56 +02:00
parent e333f040e9
commit faf44e2c61
3 changed files with 19 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/lispref/elisp.texi
View file

@ -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.

32
doc/lispref/parsing.texi
View file

@ -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

7
lisp/treesit.el
View file

@ -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.