1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
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>
|
