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 | 320 |
1 files changed, 190 insertions, 130 deletions
diff --git a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html index 1bea0dde76b..e1de2007077 100644 --- a/admin/notes/tree-sitter/html-manual/Retrieving-Node.html +++ b/admin/notes/tree-sitter/html-manual/Retrieving-Node.html @@ -33,7 +33,7 @@ developing GNU and promoting software freedom." --> <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="Accessing-Node-Information.html" rel="next" title="Accessing Node Information"> <link href="Using-Parser.html" rel="prev" title="Using Parser"> <style type="text/css"> <!-- @@ -63,77 +63,90 @@ ul.no-bullet {list-style: none} <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> +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-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. +<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 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. +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 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>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 throws <code>treesit-node-outdated</code> error. +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>beg end &optional parser-or-lang named</em><a href='#index-treesit_002dnode_002dat' class='copiable-anchor'> ¶</a></span></dt> +<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 <var>point</var>. In other words, the start of the node is equal or -greater than <var>point</var>. +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 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>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-nil, this function looks for a named node +<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"> +</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> + ⇒ #<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 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>. +<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> that calling this function on an empty line that is not -inside any top-level construct (function definition, etc) most +<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>. +to use <code>treesit-node-at</code>, described above, instead. </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 +<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 use that. +that language in <code>(treesit-parser-list)</code>, and uses 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>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"> @@ -145,17 +158,21 @@ that language in <code>(treesit-parser-list)</code> and use that. <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. +<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>Once we have a node, we can retrieve other nodes from it, or query for -information about this node. +<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> @@ -165,132 +182,162 @@ information about this node. <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>. +<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 in a list. If -<var>named</var> is non-nil, then it only retrieves named nodes. +<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-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. +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-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. +<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> and a <code>body</code>. +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-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. +<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-child-by-field-name node "body") - </pre></div> + ⇒ #<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-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>). +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> 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. +<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 all backward limit</em><a href='#index-treesit_002dsearch_002dsubtree' class='copiable-anchor'> ¶</a></span></dt> +<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>), 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. +<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 +(case-insensitively) 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, 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>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 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: +<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 (case-insensitive) 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"> o +<pre class="example"> 12 | - 3--------4-----------8 - | | | -o--o-+--1 5--+--6 9---+-----12 -| | | | | | -o o 2 7 +-+-+ +--+--+ - | | | | | - 10 11 13 14 15 + S--------3----------11 + | | | +o--o-+--o 1--+--2 6--+-----10 +| | | | +o o +-+-+ +--+--+ + | | | | | + 4 5 7 8 9 </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>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>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>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>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>. +<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>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>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 case-insensitively, 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 @@ -310,50 +357,63 @@ b 1 2 b | | b c d e 5 e </pre></div> -<p>If <var>process-fn</var> is non-nil, instead of returning the matched +<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-nil, <var>limit</var> is the number of +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>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>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-convenient-functions"></span><h3 class="heading">More convenient functions</h3> +<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 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>. +<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>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>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 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. +<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><a href='#index-treesit_002dparent_002dwhile' class='copiable-anchor'> ¶</a></span></dt> +<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 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>. +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.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> +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> |