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 | 420 |
1 files changed, 0 insertions, 420 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html deleted file mode 100644 index 16eeb0b1091..00000000000 --- a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html +++ /dev/null @@ -1,420 +0,0 @@ -<!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-2023 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-Information.html" rel="next" title="Accessing Node Information"> -<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-Information.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-retrieve-node_002c-tree_002dsitter"></span> -<span id="index-tree_002dsitter_002c-find-node"></span> -<span id="index-get-node_002c-tree_002dsitter"></span> - -<span id="index-terminology_002c-for-tree_002dsitter-functions"></span> -<p>Here’s some terminology and conventions we use when documenting -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 portion of buffer text; a larger and higher -node is higher up in the syntax tree, it contains many smaller nodes -as its children, and therefore spans a larger portion of text. -</p> -<p>When a function cannot find a node, it returns <code>nil</code>. For -convenience, all functions that take a node as argument and return -a node, also accept the node argument of <code>nil</code> and in that case -just return <code>nil</code>. -</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 signals the <code>treesit-node-outdated</code> error. -</p> -<span id="Retrieving-node-from-syntax-tree"></span><h3 class="heading">Retrieving node from syntax tree</h3> -<span id="index-retrieving-tree_002dsitter-nodes"></span> -<span id="index-syntax-tree_002c-retrieving-nodes"></span> - -<dl class="def"> -<dt id="index-treesit_002dnode_002dat"><span class="category">Function: </span><span><strong>treesit-node-at</strong> <em>pos &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 buffer position <var>pos</var>. In other words, the start of the node -is greater or equal to <var>pos</var>. -</p> -<p>When <var>parser-or-lang</var> is <code>nil</code> or omitted, this function uses -the first parser in <code>(treesit-parser-list)</code> of the current -buffer. If <var>parser-or-lang</var> is a parser object, it uses 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 uses -that. -</p> -<p>If <var>named</var> is non-<code>nil</code>, this function looks for a named node -only (see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). -</p> -<p>When <var>pos</var> is after all the text in the buffer, technically there -is no node after <var>pos</var>. But for convenience, this function will -return the last leaf node in the parse tree. If <var>strict</var> is -non-<code>nil</code>, this function will strictly comply to the semantics and -return <var>nil</var>. -</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) - ⇒ #<treesit-node (primitive_type) in 23-27> -</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 region -of buffer text between <var>beg</var> and <var>end</var>. In other words, the -start of the node is before or at <var>beg</var>, and the end of the node -is at or after <var>end</var>. -</p> -<p><em>Beware:</em> 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>, described above, instead. -</p> -<p>When <var>parser-or-lang</var> is <code>nil</code>, this function uses the first -parser in <code>(treesit-parser-list)</code> of the current buffer. If -<var>parser-or-lang</var> is a parser object, it uses 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 uses that. -</p> -<p>If <var>named</var> is non-<code>nil</code>, 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> of the current buffer, and returns the -root node generated by that parser. If it cannot find an appropriate -parser, it returns <code>nil</code>. -</p></dd></dl> - -<p>Given a node, a Lisp program can retrieve other nodes starting 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="index-syntax-tree-nodes_002c-retrieving-from-other-nodes"></span> - -<span id="By-kinship"></span><h4 class="subheading">By kinship</h4> -<span id="index-kinship_002c-syntax-tree-nodes"></span> -<span id="index-nodes_002c-by-kinship"></span> -<span id="index-syntax-tree-nodes_002c-by-kinship"></span> - -<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-<code>nil</code>, it counts only named nodes -(see <a href="Language-Definitions.html#tree_002dsitter-named-node">named node</a>). -</p> -<p>For example, in a node that represents a string <code>"text"</code>, there -are three children nodes: the opening quote <code>"</code>, the string text -<code>text</code>, and the closing quote <code>"</code>. Among these nodes, the -first child is the opening quote <code>"</code>, and the first named child -is the string text. -</p> -<p>This function returns <code>nil</code> if there is no <var>n</var>’th child. -<var>n</var> could be negative, e.g., <code>-1</code> represents the last child. -</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 as a list. If -<var>named</var> is non-<code>nil</code>, it retrieves only named nodes. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dnext_002dsibling"><span class="category">Function: </span><span><strong>treesit-node-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-<code>nil</code>, 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-node-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-<code>nil</code>, it finds the previous named sibling. -</p></dd></dl> - -<span id="By-field-name"></span><h4 class="subheading">By field name</h4> -<span id="index-nodes_002c-by-field-name"></span> -<span id="index-syntax-tree-nodes_002c-by-field-name"></span> - -<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> node and a <code>body</code> node. -</p> -<dl class="def"> -<dt id="index-treesit_002dchild_002dby_002dfield_002dname"><span class="category">Function: </span><span><strong>treesit-node-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> whose field name is -<var>field-name</var>, a string. -</p> -<div class="example"> -<pre class="example">;; Get the child that has "body" as its field name. -(treesit-node-child-by-field-name node "body") - ⇒ #<treesit-node (compound_statement) in 45-89> -</pre></div> -</dd></dl> - -<span id="By-position"></span><h4 class="subheading">By position</h4> -<span id="index-nodes_002c-by-position"></span> -<span id="index-syntax-tree-nodes_002c-by-position"></span> - -<dl class="def"> -<dt id="index-treesit_002dfirst_002dchild_002dfor_002dpos"><span class="category">Function: </span><span><strong>treesit-node-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 -buffer position <var>pos</var>. “Extends beyond” means the end of the -child node is greater or equal to <var>pos</var>. This function only looks -for immediate children of <var>node</var>, and doesn’t look in its -grandchildren. If <var>named</var> is non-<code>nil</code>, it looks for the -first 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> descendant node of <var>node</var> -that spans the region of text between positions <var>beg</var> and -<var>end</var>. It is similar to <code>treesit-node-at</code>. If <var>named</var> -is non-<code>nil</code>, it looks for smallest 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 backward all 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> itself), looking for a node for which <var>predicate</var> -returns non-<code>nil</code>. <var>predicate</var> is a regexp that is matched -against each node’s type, or a predicate function that takes a node -and returns non-<code>nil</code> if the node matches. The function returns -the first node that matches, or <code>nil</code> if none does. -</p> -<p>By default, this function only traverses named nodes, but if <var>all</var> -is non-<code>nil</code>, it traverses all the nodes. If <var>backward</var> is -non-<code>nil</code>, it traverses backwards (i.e., it visits the last child first -when traversing down the tree). If <var>limit</var> is non-<code>nil</code>, it -must be a number that limits the tree traversal to that many levels -down 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 backward all</em><a href='#index-treesit_002dsearch_002dforward' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>Like <code>treesit-search-subtree</code>, this function also traverses the -parse tree and matches each node with <var>predicate</var> (except for -<var>start</var>), where <var>predicate</var> can be a regexp or a function. -For a tree like the below where <var>start</var> is marked S, this function -traverses as numbered from 1 to 12: -</p> -<div class="example"> -<pre class="example"> 12 - | - S--------3----------11 - | | | -o--o-+--o 1--+--2 6--+-----10 -| | | | -o o +-+-+ +--+--+ - | | | | | - 4 5 7 8 9 -</pre></div> - -<p>Note that this function doesn’t traverse the subtree of <var>start</var>, -and it always traverse leaf nodes first, then upwards. -</p> -<p>Like <code>treesit-search-subtree</code>, this function only searches for -named nodes by default, but if <var>all</var> is non-<code>nil</code>, it -searches for all nodes. If <var>backward</var> is non-<code>nil</code>, it -searches backwards. -</p> -<p>While <code>treesit-search-subtree</code> traverses the subtree of a node, -this function starts with node <var>start</var> and traverses every node -that comes after it in the buffer position order, i.e., nodes with -start positions greater than the end position of <var>start</var>. -</p> -<p>In the tree shown above, <code>treesit-search-subtree</code> traverses node -S (<var>start</var>) and nodes marked with <code>o</code>, where this function -traverses the nodes marked with numbers. This function is useful for -answering questions like “what is the first node after <var>start</var> in -the buffer that satisfies some condition?” -</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>node predicate &optional start backward all</em><a href='#index-treesit_002dsearch_002dforward_002dgoto' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function moves point to the start or end of the next node after -<var>node</var> in the buffer that matches <var>predicate</var>. If <var>start</var> -is non-<code>nil</code>, stop at the beginning rather than the end of a node. -</p> -<p>This function guarantees that the matched node it returns makes -progress in terms of buffer position: the start/end position of the -returned node is always greater than that of <var>node</var>. -</p> -<p>Arguments <var>predicate</var>, <var>backward</var> and <var>all</var> are the same -as in <code>treesit-search-forward</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>It takes the subtree under <var>root</var>, and combs it so only the nodes -that match <var>predicate</var> are left. Like previous functions, the -<var>predicate</var> can be a regexp string that matches against each -node’s type, or a function that takes a node and return non-<code>nil</code> -if it matches. -</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-<code>nil</code>, instead of returning the matched -nodes, this function passes each node to <var>process-fn</var> and uses the -returned value instead. If non-<code>nil</code>, <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><span class="nolinebreak">tree-sitter-node</span></var> . (<var>child</var> …))</code><!-- /@w -->. The -<var>tree-sitter-node</var> of the root of this tree will be nil if -<var>root</var> doesn’t match <var>predicate</var>. If no node matches -<var>predicate</var>, the function returns <code>nil</code>. -</p></dd></dl> - -<span id="More-convenience-functions"></span><h3 class="heading">More convenience functions</h3> - -<dl class="def"> -<dt id="index-treesit_002dfilter_002dchild"><span class="category">Function: </span><span><strong>treesit-filter-child</strong> <em>node predicate &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 satisfy -<var>predicate</var>. -</p> -<p>The <var>predicate</var> function takes a node as the argument and should -return non-<code>nil</code> to indicate that the node should be kept. If -<var>named</var> is non-<code>nil</code>, this function only examines the 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 predicate</em><a href='#index-treesit_002dparent_002duntil' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function repeatedly finds the parents of <var>node</var>, and returns -the parent that satisfies <var>predicate</var>, a function that takes a -node as the argument. If no parent satisfies <var>predicate</var>, this -function returns <code>nil</code>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dparent_002dwhile"><span class="category">Function: </span><span><strong>treesit-parent-while</strong> <em>node predicate</em><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 nodes satisfy <var>predicate</var>, a function that -takes a node as the argument. That is, this function returns the -farthest parent that still satisfies <var>predicate</var>. -</p></dd></dl> - -<dl class="def"> -<dt id="index-treesit_002dnode_002dtop_002dlevel"><span class="category">Function: </span><span><strong>treesit-node-top-level</strong> <em>node &optional type</em><a href='#index-treesit_002dnode_002dtop_002dlevel' class='copiable-anchor'> ¶</a></span></dt> -<dd><p>This function returns the highest parent of <var>node</var> that has the -same type as <var>node</var>. If no such parent exists, it returns -<code>nil</code>. Therefore this function is also useful for testing -whether <var>node</var> is top-level. -</p> -<p>If <var>type</var> is non-<code>nil</code>, this function matches each parent’s -type with <var>type</var> as a regexp, rather than using <var>node</var>’s type. -</p></dd></dl> - -</div> -<hr> -<div class="header"> -<p> -Next: <a href="Accessing-Node-Information.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> |