diff options
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Retrieving-Node.html')
| -rw-r--r-- | admin/notes/tree-sitter/html-manual/Retrieving-Node.html | 362 |
1 files changed, 362 insertions, 0 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html new file mode 100644 index 00000000000..1bea0dde76b --- /dev/null +++ b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html @@ -0,0 +1,362 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ --> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<!-- This is the GNU Emacs Lisp Reference Manual +corresponding to Emacs version 29.0.50. + +Copyright © 1990-1996, 1998-2022 Free Software Foundation, +Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "GNU General Public License," with the +Front-Cover Texts being "A GNU Manual," and with the Back-Cover +Texts as in (a) below. A copy of the license is included in the +section entitled "GNU Free Documentation License." + +(a) The FSF's Back-Cover Text is: "You have the freedom to copy and +modify this GNU manual. Buying copies from the FSF supports it in +developing GNU and promoting software freedom." --> +<title>Retrieving Node (GNU Emacs Lisp Reference Manual)</title> + +<meta name="description" content="Retrieving Node (GNU Emacs Lisp Reference Manual)"> +<meta name="keywords" content="Retrieving Node (GNU Emacs Lisp Reference Manual)"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta name="viewport" content="width=device-width,initial-scale=1"> + +<link href="index.html" rel="start" title="Top"> +<link href="Index.html" rel="index" title="Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source"> +<link href="Accessing-Node.html" rel="next" title="Accessing Node"> +<link href="Using-Parser.html" rel="prev" title="Using Parser"> +<style type="text/css"> +<!-- +a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em} +a.summary-letter {text-decoration: none} +blockquote.indentedblock {margin-right: 0em} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +kbd {font-style: oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +span.nolinebreak {white-space: nowrap} +span.roman {font-family: initial; font-weight: normal} +span.sansserif {font-family: sans-serif; font-weight: normal} +span:hover a.copiable-anchor {visibility: visible} +ul.no-bullet {list-style: none} +--> +</style> +<link rel="stylesheet" type="text/css" href="./manual.css"> + + +</head> + +<body lang="en"> +<div class="section" id="Retrieving-Node"> +<div class="header"> +<p> +Next: <a href="Accessing-Node.html" accesskey="n" rel="next">Accessing Node Information</a>, Previous: <a href="Using-Parser.html" accesskey="p" rel="prev">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html" accesskey="u" rel="up">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<span id="Retrieving-Node-1"></span><h3 class="section">37.3 Retrieving Node</h3> + +<span id="index-tree_002dsitter-find-node"></span> +<span id="index-tree_002dsitter-get-node"></span> +<p>Before we continue, lets go over some conventions of tree-sitter +functions. +</p> +<p>We talk about a node being “smaller” or “larger”, and “lower” or +“higher”. A smaller and lower node is lower in the syntax tree and +therefore spans a smaller piece of text; a larger and higher node is +higher up in the syntax tree, containing many smaller nodes as its +children, and therefore spans a larger piece of text. +</p> +<p>When a function cannot find a node, it returns nil. And for the +convenience for function chaining, all the functions that take a node +as argument and returns a node accept the node to be nil; in that +case, the function just returns nil. +</p> +<span id="index-treesit_002dnode_002doutdated"></span> +<p>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 throws <code>treesit-node-outdated</code> error. +</p> +<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3> + +<dl class="def"> +<dt id="index-treesit_002dnode_002dat"><span class="category">Function: </span><span><strong>treesit-node-at</strong> <em>beg end &optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns the <em>smallest</em> node that starts at or after +the <var>point</var>. In other words, the start of the node is equal or +greater than <var>point</var>. +</p> +<p>When <var>parser-or-lang</var> is nil, this function uses the first parser +in <code>(treesit-parser-list)</code> in the current buffer. If +<var>parser-or-lang</var> is a parser object, it use that parser; if +<var>parser-or-lang</var> is a language, it finds the first parser using +that language in <code>(treesit-parser-list)</code> and use that. +</p> +<p>If <var>named</var> is non-nil, this function looks for a named node +only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). +</p> +<p>Example: +</p><div class="example"> +<pre class="example">;; Find the node at point in a C parser's syntax tree. +(treesit-node-at (point) 'c) + </pre></div> +</dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dnode_002don"><span class="category">Function: </span><span><strong>treesit-node-on</strong> <em>beg end &optional parser-or-lang named</em><a href='#index-treesit_002dnode_002don' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns the <em>smallest</em> node that covers the span +from <var>beg</var> to <var>end</var>. In other words, the start of the node is +less or equal to <var>beg</var>, and the end of the node is greater or +equal to <var>end</var>. +</p> +<p><em>Beware</em> that calling this function on an empty line that is not +inside any top-level construct (function definition, etc) most +probably will give you the root node, because the root node is the +smallest node that covers that empty line. Most of the time, you want +to use <code>treesit-node-at</code>. +</p> +<p>When <var>parser-or-lang</var> is nil, this function uses the first parser +in <code>(treesit-parser-list)</code> in the current buffer. If +<var>parser-or-lang</var> is a parser object, it use that parser; if +<var>parser-or-lang</var> is a language, it finds the first parser using +that language in <code>(treesit-parser-list)</code> and use that. +</p> +<p>If <var>named</var> is non-nil, this function looks for a named node only +(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dparser_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-parser-root-node</strong> <em>parser</em><a href='#index-treesit_002dparser_002droot_002dnode' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns the root node of the syntax tree generated by +<var>parser</var>. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dbuffer_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-buffer-root-node</strong> <em>&optional language</em><a href='#index-treesit_002dbuffer_002droot_002dnode' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the first parser that uses <var>language</var> in +<code>(treesit-parser-list)</code> in the current buffer, and returns the +root node of that buffer. If it cannot find an appropriate parser, +nil is returned. +</p></dd></dl> + +<p>Once we have a node, we can retrieve other nodes from it, or query for +information about this node. +</p> +<span id="Retrieving-node-from-other-nodes"></span><h3 class="heading">Retrieving node from other nodes</h3> + +<span id="By-kinship"></span><h4 class="subheading">By kinship</h4> + +<dl class="def"> +<dt id="index-treesit_002dnode_002dparent"><span class="category">Function: </span><span><strong>treesit-node-parent</strong> <em>node</em><a href='#index-treesit_002dnode_002dparent' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns the immediate parent of <var>node</var>. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dnode_002dchild"><span class="category">Function: </span><span><strong>treesit-node-child</strong> <em>node n &optional named</em><a href='#index-treesit_002dnode_002dchild' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns the <var>n</var>’th child of <var>node</var>. If +<var>named</var> is non-nil, then it only counts named nodes +(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). For example, in a node +that represents a string: <code>"text"</code>, there are three children +nodes: the opening quote <code>"</code>, the string content <code>text</code>, and +the enclosing quote <code>"</code>. Among these nodes, the first child is +the opening quote <code>"</code>, the first named child is the string +content <code>text</code>. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dnode_002dchildren"><span class="category">Function: </span><span><strong>treesit-node-children</strong> <em>node &optional named</em><a href='#index-treesit_002dnode_002dchildren' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function returns all of <var>node</var>’s children in a list. If +<var>named</var> is non-nil, then it only retrieves named nodes. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dnext_002dsibling"><span class="category">Function: </span><span><strong>treesit-next-sibling</strong> <em>node &optional named</em><a href='#index-treesit_002dnext_002dsibling' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the next sibling of <var>node</var>. If <var>named</var> is +non-nil, it finds the next named sibling. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dprev_002dsibling"><span class="category">Function: </span><span><strong>treesit-prev-sibling</strong> <em>node &optional named</em><a href='#index-treesit_002dprev_002dsibling' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the previous sibling of <var>node</var>. If +<var>named</var> is non-nil, it finds the previous named sibling. +</p></dd></dl> + +<span id="By-field-name"></span><h4 class="subheading">By field name</h4> + +<p>To make the syntax tree easier to analyze, many language definitions +assign <em>field names</em> to child nodes (see <a href="Language-Definitions.html#tree_002dsitter-node-field-name">field name</a>). For example, a <code>function_definition</code> node +could have a <code>declarator</code> and a <code>body</code>. +</p> +<dl class="def"> +<dt id="index-treesit_002dchild_002dby_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-child-by-field-name</strong> <em>node field-name</em><a href='#index-treesit_002dchild_002dby_002dfield_002dname' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the child of <var>node</var> that has <var>field-name</var> +as its field name. +</p> +<div class="example"> +<pre class="example">;; Get the child that has "body" as its field name. +(treesit-child-by-field-name node "body") + </pre></div> +</dd></dl> + +<span id="By-position"></span><h4 class="subheading">By position</h4> + +<dl class="def"> +<dt id="index-treesit_002dfirst_002dchild_002dfor_002dpos"><span class="category">Function: </span><span><strong>treesit-first-child-for-pos</strong> <em>node pos &optional named</em><a href='#index-treesit_002dfirst_002dchild_002dfor_002dpos' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the first child of <var>node</var> that extends beyond +<var>pos</var>. “Extend beyond” means the end of the child node >= +<var>pos</var>. This function only looks for immediate children of +<var>node</var>, and doesn’t look in its grand children. If <var>named</var> is +non-nil, it only looks for named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dnode_002ddescendant_002dfor_002drange"><span class="category">Function: </span><span><strong>treesit-node-descendant-for-range</strong> <em>node beg end &optional named</em><a href='#index-treesit_002dnode_002ddescendant_002dfor_002drange' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds the <em>smallest</em> child/grandchild... of +<var>node</var> that spans the range from <var>beg</var> to <var>end</var>. It is +similar to <code>treesit-node-at</code>. If <var>named</var> is non-nil, it only +looks for named child. +</p></dd></dl> + +<span id="Searching-for-node"></span><h3 class="heading">Searching for node</h3> + +<dl class="def"> +<dt id="index-treesit_002dsearch_002dsubtree"><span class="category">Function: </span><span><strong>treesit-search-subtree</strong> <em>node predicate &optional all backward limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function traverses the subtree of <var>node</var> (including +<var>node</var>), and match <var>predicate</var> with each node along the way. +And <var>predicate</var> is a regexp that matches (case-insensitively) +against each node’s type, or a function that takes a node and returns +nil/non-nil. If a node matches, that node is returned, if no node +ever matches, nil is returned. +</p> +<p>By default, this function only traverses named nodes, if <var>all</var> is +non-nil, it traverses all nodes. If <var>backward</var> is non-nil, it +traverses backwards. If <var>limit</var> is non-nil, it only traverses +that number of levels down in the tree. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dsearch_002dforward"><span class="category">Function: </span><span><strong>treesit-search-forward</strong> <em>start predicate &optional all backward up</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function is somewhat similar to <code>treesit-search-subtree</code>. +It also traverse the parse tree and match each node with +<var>predicate</var> (except for <var>start</var>), where <var>predicate</var> can be +a (case-insensitive) regexp or a function. For a tree like the below +where <var>start</var> is marked 1, this function traverses as numbered: +</p> +<div class="example"> +<pre class="example"> o + | + 3--------4-----------8 + | | | +o--o-+--1 5--+--6 9---+-----12 +| | | | | | +o o 2 7 +-+-+ +--+--+ + | | | | | + 10 11 13 14 15 +</pre></div> + +<p>Same as in <code>treesit-search-subtree</code>, this function only searches +for named nodes by default. But if <var>all</var> is non-nil, it searches +for all nodes. If <var>backward</var> is non-nil, it searches backwards. +</p> +<p>If <var>up</var> is non-nil, this function will only traverse to siblings +and parents. In that case, only 1 3 4 8 would be traversed. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dsearch_002dforward_002dgoto"><span class="category">Function: </span><span><strong>treesit-search-forward-goto</strong> <em>predicate side &optional all backward up</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function jumps to the start or end of the next node in buffer +that matches <var>predicate</var>. Parameters <var>predicate</var>, <var>all</var>, +<var>backward</var>, and <var>up</var> are the same as in +<code>treesit-search-forward</code>. And <var>side</var> controls which side of +the matched no do we stop at, it can be <code>start</code> or <code>end</code>. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dinduce_002dsparse_002dtree"><span class="category">Function: </span><span><strong>treesit-induce-sparse-tree</strong> <em>root predicate &optional process-fn limit</em><a href='#index-treesit_002dinduce_002dsparse_002dtree' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function creates a sparse tree from <var>root</var>’s subtree. +</p> +<p>Basically, it takes the subtree under <var>root</var>, and combs it so only +the nodes that match <var>predicate</var> are left, like picking out grapes +on the vine. Like previous functions, <var>predicate</var> can be a regexp +string that matches against each node’s type case-insensitively, or a +function that takes a node and return nil/non-nil. +</p> +<p>For example, for a subtree on the left that consist of both numbers +and letters, if <var>predicate</var> is “letter only”, the returned tree +is the one on the right. +</p> +<div class="example"> +<pre class="example"> a a a + | | | ++---+---+ +---+---+ +---+---+ +| | | | | | | | | +b 1 2 b | | b c d + | | => | | => | + c +--+ c + e + | | | | | + +--+ d 4 +--+ d + | | | + e 5 e +</pre></div> + +<p>If <var>process-fn</var> is non-nil, instead of returning the matched +nodes, this function passes each node to <var>process-fn</var> and uses the +returned value instead. If non-nil, <var>limit</var> is the number of +levels to go down from <var>root</var>. +</p> +<p>Each node in the returned tree looks like <code>(<var>tree-sitter +node</var> . (<var>child</var> ...))</code>. The <var>tree-sitter node</var> of the root +of this tree will be nil if <var>ROOT</var> doesn’t match <var>pred</var>. If +no node matches <var>predicate</var>, return nil. +</p></dd></dl> + +<span id="More-convenient-functions"></span><h3 class="heading">More convenient functions</h3> + +<dl class="def"> +<dt id="index-treesit_002dfilter_002dchild"><span class="category">Function: </span><span><strong>treesit-filter-child</strong> <em>node pred &optional named</em><a href='#index-treesit_002dfilter_002dchild' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function finds immediate children of <var>node</var> that satisfies +<var>pred</var>. +</p> +<p>Function <var>pred</var> takes the child node as the argument and should +return non-nil to indicated keeping the child. If <var>named</var> +non-nil, this function only searches for named nodes. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dparent_002duntil"><span class="category">Function: </span><span><strong>treesit-parent-until</strong> <em>node pred</em><a href='#index-treesit_002dparent_002duntil' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function repeatedly finds the parent of <var>node</var>, and returns +the parent if it satisfies <var>pred</var> (which takes the parent as the +argument). If no parent satisfies <var>pred</var>, this function returns +nil. +</p></dd></dl> + +<dl class="def"> +<dt id="index-treesit_002dparent_002dwhile"><span class="category">Function: </span><span><strong>treesit-parent-while</strong><a href='#index-treesit_002dparent_002dwhile' class='copiable-anchor'> ¶</a></span></dt> +<dd><p>This function repeatedly finds the parent of <var>node</var>, and keeps +doing so as long as the parent satisfies <var>pred</var> (which takes the +parent as the single argument). I.e., this function returns the +farthest parent that still satisfies <var>pred</var>. +</p></dd></dl> + +</div> +<hr> +<div class="header"> +<p> +Next: <a href="Accessing-Node.html">Accessing Node Information</a>, Previous: <a href="Using-Parser.html">Using Tree-sitter Parser</a>, Up: <a href="Parsing-Program-Source.html">Parsing Program Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Index.html" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |