aboutsummaryrefslogtreecommitdiffstats
path: root/admin/notes/tree-sitter/html-manual/Retrieving-Node.html
diff options
context:
space:
mode:
authorYuan Fu2022-10-05 14:11:33 -0700
committerYuan Fu2022-10-05 14:11:33 -0700
commitcb183f6467401fb5ed2b7fc98ca75be9d943cbe3 (patch)
treeef42ea6ae71e0829d900ffb46d8306fbba962a8e /admin/notes/tree-sitter/html-manual/Retrieving-Node.html
parent1ea503ed4b3a14b3dc0a597cfbfe57d73b871422 (diff)
downloademacs-cb183f6467401fb5ed2b7fc98ca75be9d943cbe3.tar.gz
emacs-cb183f6467401fb5ed2b7fc98ca75be9d943cbe3.zip
Add tree-sitter admin notes
starter-guide: Guide on writing major mode features. build-module: Script for building official language definitions. html-manual: HTML version of the manual for easy access. * admin/notes/tree-sitter/build-module/README: New file. * admin/notes/tree-sitter/build-module/batch.sh: New file. * admin/notes/tree-sitter/build-module/build.sh: New file. * admin/notes/tree-sitter/starter-guide: New file. * admin/notes/tree-sitter/html-manual/Accessing-Node.html: New file. * admin/notes/tree-sitter/html-manual/Language-Definitions.html: New file. * admin/notes/tree-sitter/html-manual/Multiple-Languages.html: New file. * admin/notes/tree-sitter/html-manual/Parser_002dbased-Font-Lock.html: New file. * admin/notes/tree-sitter/html-manual/Parser_002dbased-Indentation.html: New file. * admin/notes/tree-sitter/html-manual/Parsing-Program-Source.html: New file. * admin/notes/tree-sitter/html-manual/Pattern-Matching.html: New file. * admin/notes/tree-sitter/html-manual/Retrieving-Node.html: New file. * admin/notes/tree-sitter/html-manual/Tree_002dsitter-C-API.html: New file. * admin/notes/tree-sitter/html-manual/Using-Parser.html: New file. * admin/notes/tree-sitter/html-manual/build-manual.sh: New file. * admin/notes/tree-sitter/html-manual/manual.css: New file.
Diffstat (limited to 'admin/notes/tree-sitter/html-manual/Retrieving-Node.html')
-rw-r--r--admin/notes/tree-sitter/html-manual/Retrieving-Node.html362
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 @@
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<html>
3<!-- Created by GNU Texinfo 6.8, https://www.gnu.org/software/texinfo/ -->
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6<!-- This is the GNU Emacs Lisp Reference Manual
7corresponding to Emacs version 29.0.50.
8
9Copyright © 1990-1996, 1998-2022 Free Software Foundation,
10Inc.
11
12Permission is granted to copy, distribute and/or modify this document
13under the terms of the GNU Free Documentation License, Version 1.3 or
14any later version published by the Free Software Foundation; with the
15Invariant Sections being "GNU General Public License," with the
16Front-Cover Texts being "A GNU Manual," and with the Back-Cover
17Texts as in (a) below. A copy of the license is included in the
18section entitled "GNU Free Documentation License."
19
20(a) The FSF's Back-Cover Text is: "You have the freedom to copy and
21modify this GNU manual. Buying copies from the FSF supports it in
22developing GNU and promoting software freedom." -->
23<title>Retrieving Node (GNU Emacs Lisp Reference Manual)</title>
24
25<meta name="description" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
26<meta name="keywords" content="Retrieving Node (GNU Emacs Lisp Reference Manual)">
27<meta name="resource-type" content="document">
28<meta name="distribution" content="global">
29<meta name="Generator" content="makeinfo">
30<meta name="viewport" content="width=device-width,initial-scale=1">
31
32<link href="index.html" rel="start" title="Top">
33<link href="Index.html" rel="index" title="Index">
34<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
35<link href="Parsing-Program-Source.html" rel="up" title="Parsing Program Source">
36<link href="Accessing-Node.html" rel="next" title="Accessing Node">
37<link href="Using-Parser.html" rel="prev" title="Using Parser">
38<style type="text/css">
39<!--
40a.copiable-anchor {visibility: hidden; text-decoration: none; line-height: 0em}
41a.summary-letter {text-decoration: none}
42blockquote.indentedblock {margin-right: 0em}
43div.display {margin-left: 3.2em}
44div.example {margin-left: 3.2em}
45kbd {font-style: oblique}
46pre.display {font-family: inherit}
47pre.format {font-family: inherit}
48pre.menu-comment {font-family: serif}
49pre.menu-preformatted {font-family: serif}
50span.nolinebreak {white-space: nowrap}
51span.roman {font-family: initial; font-weight: normal}
52span.sansserif {font-family: sans-serif; font-weight: normal}
53span:hover a.copiable-anchor {visibility: visible}
54ul.no-bullet {list-style: none}
55-->
56</style>
57<link rel="stylesheet" type="text/css" href="./manual.css">
58
59
60</head>
61
62<body lang="en">
63<div class="section" id="Retrieving-Node">
64<div class="header">
65<p>
66Next: <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> &nbsp; [<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>
67</div>
68<hr>
69<span id="Retrieving-Node-1"></span><h3 class="section">37.3 Retrieving Node</h3>
70
71<span id="index-tree_002dsitter-find-node"></span>
72<span id="index-tree_002dsitter-get-node"></span>
73<p>Before we continue, lets go over some conventions of tree-sitter
74functions.
75</p>
76<p>We talk about a node being &ldquo;smaller&rdquo; or &ldquo;larger&rdquo;, and &ldquo;lower&rdquo; or
77&ldquo;higher&rdquo;. A smaller and lower node is lower in the syntax tree and
78therefore spans a smaller piece of text; a larger and higher node is
79higher up in the syntax tree, containing many smaller nodes as its
80children, and therefore spans a larger piece of text.
81</p>
82<p>When a function cannot find a node, it returns nil. And for the
83convenience for function chaining, all the functions that take a node
84as argument and returns a node accept the node to be nil; in that
85case, the function just returns nil.
86</p>
87<span id="index-treesit_002dnode_002doutdated"></span>
88<p>Nodes are not automatically updated when the associated buffer is
89modified. And there is no way to update a node once it is retrieved.
90Using an outdated node throws <code>treesit-node-outdated</code> error.
91</p>
92<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3>
93
94<dl class="def">
95<dt id="index-treesit_002dnode_002dat"><span class="category">Function: </span><span><strong>treesit-node-at</strong> <em>beg end &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> &para;</a></span></dt>
96<dd><p>This function returns the <em>smallest</em> node that starts at or after
97the <var>point</var>. In other words, the start of the node is equal or
98greater than <var>point</var>.
99</p>
100<p>When <var>parser-or-lang</var> is nil, this function uses the first parser
101in <code>(treesit-parser-list)</code> in the current buffer. If
102<var>parser-or-lang</var> is a parser object, it use that parser; if
103<var>parser-or-lang</var> is a language, it finds the first parser using
104that language in <code>(treesit-parser-list)</code> and use that.
105</p>
106<p>If <var>named</var> is non-nil, this function looks for a named node
107only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
108</p>
109<p>Example:
110</p><div class="example">
111<pre class="example">;; Find the node at point in a C parser's syntax tree.
112(treesit-node-at (point) 'c)
113 </pre></div>
114</dd></dl>
115
116<dl class="def">
117<dt id="index-treesit_002dnode_002don"><span class="category">Function: </span><span><strong>treesit-node-on</strong> <em>beg end &amp;optional parser-or-lang named</em><a href='#index-treesit_002dnode_002don' class='copiable-anchor'> &para;</a></span></dt>
118<dd><p>This function returns the <em>smallest</em> node that covers the span
119from <var>beg</var> to <var>end</var>. In other words, the start of the node is
120less or equal to <var>beg</var>, and the end of the node is greater or
121equal to <var>end</var>.
122</p>
123<p><em>Beware</em> that calling this function on an empty line that is not
124inside any top-level construct (function definition, etc) most
125probably will give you the root node, because the root node is the
126smallest node that covers that empty line. Most of the time, you want
127to use <code>treesit-node-at</code>.
128</p>
129<p>When <var>parser-or-lang</var> is nil, this function uses the first parser
130in <code>(treesit-parser-list)</code> in the current buffer. If
131<var>parser-or-lang</var> is a parser object, it use that parser; if
132<var>parser-or-lang</var> is a language, it finds the first parser using
133that language in <code>(treesit-parser-list)</code> and use that.
134</p>
135<p>If <var>named</var> is non-nil, this function looks for a named node only
136(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
137</p></dd></dl>
138
139<dl class="def">
140<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'> &para;</a></span></dt>
141<dd><p>This function returns the root node of the syntax tree generated by
142<var>parser</var>.
143</p></dd></dl>
144
145<dl class="def">
146<dt id="index-treesit_002dbuffer_002droot_002dnode"><span class="category">Function: </span><span><strong>treesit-buffer-root-node</strong> <em>&amp;optional language</em><a href='#index-treesit_002dbuffer_002droot_002dnode' class='copiable-anchor'> &para;</a></span></dt>
147<dd><p>This function finds the first parser that uses <var>language</var> in
148<code>(treesit-parser-list)</code> in the current buffer, and returns the
149root node of that buffer. If it cannot find an appropriate parser,
150nil is returned.
151</p></dd></dl>
152
153<p>Once we have a node, we can retrieve other nodes from it, or query for
154information about this node.
155</p>
156<span id="Retrieving-node-from-other-nodes"></span><h3 class="heading">Retrieving node from other nodes</h3>
157
158<span id="By-kinship"></span><h4 class="subheading">By kinship</h4>
159
160<dl class="def">
161<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'> &para;</a></span></dt>
162<dd><p>This function returns the immediate parent of <var>node</var>.
163</p></dd></dl>
164
165<dl class="def">
166<dt id="index-treesit_002dnode_002dchild"><span class="category">Function: </span><span><strong>treesit-node-child</strong> <em>node n &amp;optional named</em><a href='#index-treesit_002dnode_002dchild' class='copiable-anchor'> &para;</a></span></dt>
167<dd><p>This function returns the <var>n</var>&rsquo;th child of <var>node</var>. If
168<var>named</var> is non-nil, then it only counts named nodes
169(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). For example, in a node
170that represents a string: <code>&quot;text&quot;</code>, there are three children
171nodes: the opening quote <code>&quot;</code>, the string content <code>text</code>, and
172the enclosing quote <code>&quot;</code>. Among these nodes, the first child is
173the opening quote <code>&quot;</code>, the first named child is the string
174content <code>text</code>.
175</p></dd></dl>
176
177<dl class="def">
178<dt id="index-treesit_002dnode_002dchildren"><span class="category">Function: </span><span><strong>treesit-node-children</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnode_002dchildren' class='copiable-anchor'> &para;</a></span></dt>
179<dd><p>This function returns all of <var>node</var>&rsquo;s children in a list. If
180<var>named</var> is non-nil, then it only retrieves named nodes.
181</p></dd></dl>
182
183<dl class="def">
184<dt id="index-treesit_002dnext_002dsibling"><span class="category">Function: </span><span><strong>treesit-next-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dnext_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
185<dd><p>This function finds the next sibling of <var>node</var>. If <var>named</var> is
186non-nil, it finds the next named sibling.
187</p></dd></dl>
188
189<dl class="def">
190<dt id="index-treesit_002dprev_002dsibling"><span class="category">Function: </span><span><strong>treesit-prev-sibling</strong> <em>node &amp;optional named</em><a href='#index-treesit_002dprev_002dsibling' class='copiable-anchor'> &para;</a></span></dt>
191<dd><p>This function finds the previous sibling of <var>node</var>. If
192<var>named</var> is non-nil, it finds the previous named sibling.
193</p></dd></dl>
194
195<span id="By-field-name"></span><h4 class="subheading">By field name</h4>
196
197<p>To make the syntax tree easier to analyze, many language definitions
198assign <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
199could have a <code>declarator</code> and a <code>body</code>.
200</p>
201<dl class="def">
202<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'> &para;</a></span></dt>
203<dd><p>This function finds the child of <var>node</var> that has <var>field-name</var>
204as its field name.
205</p>
206<div class="example">
207<pre class="example">;; Get the child that has &quot;body&quot; as its field name.
208(treesit-child-by-field-name node &quot;body&quot;)
209 </pre></div>
210</dd></dl>
211
212<span id="By-position"></span><h4 class="subheading">By position</h4>
213
214<dl class="def">
215<dt id="index-treesit_002dfirst_002dchild_002dfor_002dpos"><span class="category">Function: </span><span><strong>treesit-first-child-for-pos</strong> <em>node pos &amp;optional named</em><a href='#index-treesit_002dfirst_002dchild_002dfor_002dpos' class='copiable-anchor'> &para;</a></span></dt>
216<dd><p>This function finds the first child of <var>node</var> that extends beyond
217<var>pos</var>. &ldquo;Extend beyond&rdquo; means the end of the child node &gt;=
218<var>pos</var>. This function only looks for immediate children of
219<var>node</var>, and doesn&rsquo;t look in its grand children. If <var>named</var> is
220non-nil, it only looks for named child (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>).
221</p></dd></dl>
222
223<dl class="def">
224<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 &amp;optional named</em><a href='#index-treesit_002dnode_002ddescendant_002dfor_002drange' class='copiable-anchor'> &para;</a></span></dt>
225<dd><p>This function finds the <em>smallest</em> child/grandchild... of
226<var>node</var> that spans the range from <var>beg</var> to <var>end</var>. It is
227similar to <code>treesit-node-at</code>. If <var>named</var> is non-nil, it only
228looks for named child.
229</p></dd></dl>
230
231<span id="Searching-for-node"></span><h3 class="heading">Searching for node</h3>
232
233<dl class="def">
234<dt id="index-treesit_002dsearch_002dsubtree"><span class="category">Function: </span><span><strong>treesit-search-subtree</strong> <em>node predicate &amp;optional all backward limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> &para;</a></span></dt>
235<dd><p>This function traverses the subtree of <var>node</var> (including
236<var>node</var>), and match <var>predicate</var> with each node along the way.
237And <var>predicate</var> is a regexp that matches (case-insensitively)
238against each node&rsquo;s type, or a function that takes a node and returns
239nil/non-nil. If a node matches, that node is returned, if no node
240ever matches, nil is returned.
241</p>
242<p>By default, this function only traverses named nodes, if <var>all</var> is
243non-nil, it traverses all nodes. If <var>backward</var> is non-nil, it
244traverses backwards. If <var>limit</var> is non-nil, it only traverses
245that number of levels down in the tree.
246</p></dd></dl>
247
248<dl class="def">
249<dt id="index-treesit_002dsearch_002dforward"><span class="category">Function: </span><span><strong>treesit-search-forward</strong> <em>start predicate &amp;optional all backward up</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> &para;</a></span></dt>
250<dd><p>This function is somewhat similar to <code>treesit-search-subtree</code>.
251It also traverse the parse tree and match each node with
252<var>predicate</var> (except for <var>start</var>), where <var>predicate</var> can be
253a (case-insensitive) regexp or a function. For a tree like the below
254where <var>start</var> is marked 1, this function traverses as numbered:
255</p>
256<div class="example">
257<pre class="example"> o
258 |
259 3--------4-----------8
260 | | |
261o--o-+--1 5--+--6 9---+-----12
262| | | | | |
263o o 2 7 +-+-+ +--+--+
264 | | | | |
265 10 11 13 14 15
266</pre></div>
267
268<p>Same as in <code>treesit-search-subtree</code>, this function only searches
269for named nodes by default. But if <var>all</var> is non-nil, it searches
270for all nodes. If <var>backward</var> is non-nil, it searches backwards.
271</p>
272<p>If <var>up</var> is non-nil, this function will only traverse to siblings
273and parents. In that case, only 1 3 4 8 would be traversed.
274</p></dd></dl>
275
276<dl class="def">
277<dt id="index-treesit_002dsearch_002dforward_002dgoto"><span class="category">Function: </span><span><strong>treesit-search-forward-goto</strong> <em>predicate side &amp;optional all backward up</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> &para;</a></span></dt>
278<dd><p>This function jumps to the start or end of the next node in buffer
279that matches <var>predicate</var>. Parameters <var>predicate</var>, <var>all</var>,
280<var>backward</var>, and <var>up</var> are the same as in
281<code>treesit-search-forward</code>. And <var>side</var> controls which side of
282the matched no do we stop at, it can be <code>start</code> or <code>end</code>.
283</p></dd></dl>
284
285<dl class="def">
286<dt id="index-treesit_002dinduce_002dsparse_002dtree"><span class="category">Function: </span><span><strong>treesit-induce-sparse-tree</strong> <em>root predicate &amp;optional process-fn limit</em><a href='#index-treesit_002dinduce_002dsparse_002dtree' class='copiable-anchor'> &para;</a></span></dt>
287<dd><p>This function creates a sparse tree from <var>root</var>&rsquo;s subtree.
288</p>
289<p>Basically, it takes the subtree under <var>root</var>, and combs it so only
290the nodes that match <var>predicate</var> are left, like picking out grapes
291on the vine. Like previous functions, <var>predicate</var> can be a regexp
292string that matches against each node&rsquo;s type case-insensitively, or a
293function that takes a node and return nil/non-nil.
294</p>
295<p>For example, for a subtree on the left that consist of both numbers
296and letters, if <var>predicate</var> is &ldquo;letter only&rdquo;, the returned tree
297is the one on the right.
298</p>
299<div class="example">
300<pre class="example"> a a a
301 | | |
302+---+---+ +---+---+ +---+---+
303| | | | | | | | |
304b 1 2 b | | b c d
305 | | =&gt; | | =&gt; |
306 c +--+ c + e
307 | | | | |
308 +--+ d 4 +--+ d
309 | | |
310 e 5 e
311</pre></div>
312
313<p>If <var>process-fn</var> is non-nil, instead of returning the matched
314nodes, this function passes each node to <var>process-fn</var> and uses the
315returned value instead. If non-nil, <var>limit</var> is the number of
316levels to go down from <var>root</var>.
317</p>
318<p>Each node in the returned tree looks like <code>(<var>tree-sitter
319node</var> . (<var>child</var> ...))</code>. The <var>tree-sitter node</var> of the root
320of this tree will be nil if <var>ROOT</var> doesn&rsquo;t match <var>pred</var>. If
321no node matches <var>predicate</var>, return nil.
322</p></dd></dl>
323
324<span id="More-convenient-functions"></span><h3 class="heading">More convenient functions</h3>
325
326<dl class="def">
327<dt id="index-treesit_002dfilter_002dchild"><span class="category">Function: </span><span><strong>treesit-filter-child</strong> <em>node pred &amp;optional named</em><a href='#index-treesit_002dfilter_002dchild' class='copiable-anchor'> &para;</a></span></dt>
328<dd><p>This function finds immediate children of <var>node</var> that satisfies
329<var>pred</var>.
330</p>
331<p>Function <var>pred</var> takes the child node as the argument and should
332return non-nil to indicated keeping the child. If <var>named</var>
333non-nil, this function only searches for named nodes.
334</p></dd></dl>
335
336<dl class="def">
337<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'> &para;</a></span></dt>
338<dd><p>This function repeatedly finds the parent of <var>node</var>, and returns
339the parent if it satisfies <var>pred</var> (which takes the parent as the
340argument). If no parent satisfies <var>pred</var>, this function returns
341nil.
342</p></dd></dl>
343
344<dl class="def">
345<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'> &para;</a></span></dt>
346<dd><p>This function repeatedly finds the parent of <var>node</var>, and keeps
347doing so as long as the parent satisfies <var>pred</var> (which takes the
348parent as the single argument). I.e., this function returns the
349farthest parent that still satisfies <var>pred</var>.
350</p></dd></dl>
351
352</div>
353<hr>
354<div class="header">
355<p>
356Next: <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> &nbsp; [<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>
357</div>
358
359
360
361</body>
362</html>
generated by cgit v1.2.1 (git 2.18.0) at 2026-02-21 14:25:16 +0000