Tree-sitter関数をドキュメント化する際に使用する用語や慣習をいくつか紹介します。
構文木のノードは、バッファ内のプログラムテキストの一部をまたいでいます。あるノードが別のノードよりもバッファテキストのより小さい範囲、あるいはより大きい範囲をまたいでいる場合、そのノードは他方のノードよりも「小さい」あるいは「大きい」と言います。木のより深い位置（「下位」）にあるノードは、木のより上位にあるノードの子であるため、下位のノードは常にノード階層において上位にあるノードよりも小さくなります。構文木のより上位にあるノードは、1つ以上のより小さいノードを子として持つため、バッファテキストのより広い範囲をまたいでいます。
関数がノードを見つけられない場合は、nil
を返します。便宜上、ノードを引数として受け取りノードを返すすべての関数は、nil
のノード引数も受け付け、その場合には単に nil を返します。
関連付けられたバッファが変更されてもノードは自動的に更新されず、一度取得したノードを更新する方法もありません。古いノードを使用すると、treesit-node-outdated エラーが発生します。
Tree-sitterノードの印刷表現では、印刷表現と読み取り構文で説明されているハッシュ表記が用いられます。形式は ‘#<treesit-node type in pos1-pos2>’ となり、ここで type はノードの型（バッファで使用されるTree-sitter文法に由来します）、pos1 と pos2 はノードのスパンのバッファ位置となります。Tree-sitterノードに読み取り構文はありません。
この関数は、バッファ位置 pos にあるリーフノードを返します。リーフノードとは、子ノードを持たないノードのことです。
この関数は、スパンが pos をカバーするノードを返そうとします。具体的には、ノードの開始位置が pos 以下であり、かつノードの終了位置が pos 以上であるノードを返します。
リーフノードのスパンが pos をカバーしない場合（例：pos が2つのリーフノード間の空白にある場合）、この関数は pos の後に続く最初のリーフノードを返します。
最後に、pos の後にリーフノードが存在しない場合は、pos より前の最初のリーフノードを返す。
parser-or-lang がパーサーオブジェクトの場合、この関数はそのパーサーを使用します。parser-or-lang
が言語の場合、この関数は現在のバッファ内にあるその言語用の最初のパーサーを使用するか、存在しない場合は新たに作成します。parser-or-lang が nil の場合、この関数は
treesit-language-at を呼び出すことで pos の言語を推測しようとします（複数言語のテキストの解析 を参照）。
この関数が返すのに適したノードを見つけられない場合は、nil を返します。
named が nil
でない場合、この関数は名前付きノード（名前付きノード
を参照）のみを検索します。
例：
;; Find the node at point in a C parser's syntax tree. (treesit-node-at (point) 'c) ⇒ #<treesit-node primitive_type in 23-27>
This function returns the smallest node that covers the region of buffer text between beg and end. In other words, the start of the node is before or at beg, and the end of the node is at or after end.
注意：
トップレベル構造（関数定義など）に含まれない空行でこの関数を呼び出すと、おそらくルートノードが返されます。これは、ルートノードがその空行をカバーする最小のノードであるためです。ほとんどの場合、代わりに
treesit-node-at を使用することが推奨されます。
parser-or-lang がパーサーオブジェクトの場合、この関数はそのパーサーを使用します。parser-or-lang
が言語の場合、この関数は現在のバッファ内にあるその言語用の最初のパーサーを使用するか、存在しない場合は新たに作成します。parser-or-lang が nil の場合、この関数は
treesit-language-at を呼び出すことで beg の言語を推測しようとします。
named が nil
でない場合、この関数は名前付きノードのみを検索します（名前付きノードを参照）。
この関数は、parser によって生成された構文木のルートノードを返します。
この関数は、現在のバッファ内で language
用の最初のパーサーを探すか、存在しない場合は作成し、そのパーサーによって生成されたルートノードを返します。 language が省略されている場合は、パーサーリストの最初のパーサーを使用します。
適切なパーサーが見つからない場合は、nil を返します。
あるノードが与えられたとき、Lispプログラムはそのノードを起点として他のノードを取得したり、そのノードに関する情報を照会したりすることができます。
この関数は、nodeの直上の親要素を返します。
パースツリーにおいて node の深さが1000レベルを超える場合、戻り値は未定義となります。現在は
nil を返しますが、将来的には変更される可能性があります。
この関数は、nodeのn番目の子を返します。namedがnilでない場合、名前付きノード（名前付きノードを参照）のみをカウントします。
例えば、文字列 "text" を表すノードには、開始クォート "、文字列テキスト text、終了クォート
" という3つの子ノードがあります。これらのノードのうち、最初の子は開始クォート
" であり、最初の名前付き子は文字列テキストです。
この関数は、n番目の子要素が存在しない場合にnilを返します。nは負の値を取ることができ、例えば−1は最後の子要素を表します。
この関数は、nodeのすべての子要素をリストとして返します。namedがnil以外の場合は、名前付きノードのみを取得します。
この関数は node の次の兄弟要素を探します。named
が nil でない場合は、次の名前付き兄弟要素を探します。
この関数は node の直前の兄弟要素を探します。named
が nil でない場合は、直前の名前付き兄弟要素を探します。
構文木を解析しやすくするため、多くの言語文法では子ノードにフィールド名を割り当てています（フィールド名を参照）。例えば、function_definitionノードはdeclarator子とbody子を持つことができます。
この関数は、フィールド名が文字列 field-name である node の子要素を検索します。
;; 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>
この関数は、バッファ位置 pos を超えて延びている node の最初の子要素を検索します。「超えて延びている」とは、子ノードの終端が pos 以上であることを意味します。この関数は node
の直接の子要素のみを検索し、その孫要素までは検索しません。named が nil 以外である場合は、最初の名前付き子要素（名前付きノード
を参照）を検索します。
この関数は、位置 beg と end
の間のテキスト領域にまたがる node の最小の子孫ノードを探します。これは treesit-node-at と同様です。named が
nil でない場合は、最小の名前付き子要素を探します。
この関数は node の部分木（node
自体を含む）を走査し、predicate が nil
以外を返すノードを探します。predicate
は、各ノードの型に照合される正規表現、またはノードを受け取り、一致した場合に nil
以外を返す述語関数です。predicate は thing シンボルまたは thing
定義であることもできます（ユーザー定義の「Things」とナビゲーション を参照）。未定義の
thing を使用してもエラーは発生せず、関数は単に nil を返します。
この関数は、最初に一致するノードを返すか、predicate に一致するものがない場合は nil を返します。
デフォルトでは、この関数は名前付きノードのみを走査しますが、all が nil 以外の場合は、すべてのノードを走査します。backward
が nil
以外の場合は、逆順に走査します（つまり、ツリーを下る際に最後の子ノードから先に訪問します）。depth が
nil 以外の場合は、ツリー走査をその階層数までに制限する数値である必要があります。depth が nil の場合は、デフォルトで 1000
となります。
treesit-search-subtreeと同様に、この関数も構文木を走査し、各ノードをpredicate（startを除く）と照合します。ここでpredicateには正規表現または述語関数を指定できます。predicateにはシングシンボルまたはシング定義を指定することも可能です（ユーザー定義の「シング」とナビゲーションを参照）。未定義のシングを使用してもエラーは発生せず、関数は単にnilを返します。
以下のような、startに‘S’と記された木に対して、この関数は1から12までの番号順に走査します：
12
|
S--------3----------11
| | |
o--o-+--o 1--+--2 6--+-----10
| | | |
o o +-+-+ +--+--+
| | | | |
4 5 7 8 9
なお、この関数はstartの部分木を走査せず、常に葉ノードを先に走査してから上方向へ移動することに注意してください。
treesit-search-subtreeと同様に、この関数はデフォルトでは名前付きノードのみを検索しますが、allがnil以外の場合はすべてのノードを検索します。backwardがnil以外の場合は、逆順に検索します。
treesit-search-subtree
がノードのサブツリーを走査するのに対し、この関数はノード start
から開始し、バッファの位置順でそれに続くすべてのノード、すなわち開始位置が start
の終了位置より大きいノードを走査します。
上記の木において、treesit-search-subtreeはノード‘S’ (start) およびoと記されたノードを辿りますが、この関数は数値で記されたノードを辿ります。この関数は、「バッファ内でstartの次にあり、ある条件を満たす最初のノードは何か」といった問いに答える際に有用です。
この関数は、predicateに一致するバッファ内のnodeの次のノードの先頭または末尾にポイントを移動します。startがnilでない場合は、ノードの末尾ではなく先頭で停止します。
この関数は、返されるマッチしたノードがバッファ位置において前進することを保証します。すなわち、返されるノードの開始/終了位置は、常に node のそれよりも大きくなります。
引数 predicate、backward、および all は treesit-search-forward
と同じです。
この関数は、rootの部分木から疎な木を生成します。
root 配下のサブツリーを取得し、predicate
に一致するノードのみが残るようにフィルタリングします。これまでの関数と同様に、predicate
には各ノードの型に一致する正規表現文字列、またはノードを受け取り、一致した場合に non-nil
を返す関数を指定できます。predicate には、thing シンボルまたは thing
定義を指定することも可能です（ユーザー定義の「Things」とナビゲーションを参照）。未定義の
thing を使用してもエラーは発生せず、関数は単に nil を返します。
例えば、数値と文字の両方からなる左側の部分木において、predicateが「文字のみ」である場合、返される木は右側のものになります。
a a a
| | |
+---+---+ +---+---+ +---+---+
| | | | | | | | |
b 1 2 b | | b c d
| | => | | => |
c +--+ c + e
| | | | |
+--+ d 4 +--+ d
| | |
e 5 e
process-fn が nil
以外の場合、この関数は一致したノードを返す代わりに、各ノードを process-fn
に渡し、その戻り値を使用します。 nil 以外の場合、depth は root から辿るレベル数を制限します。 depth が nil の場合、デフォルトは 1000
となります。
返される木の各ノードは (tree-sitter-node . (child …)) のような形式になります。この木のルートの tree-sitter-node は、root が predicate に一致しない場合に nil
となります。predicate に一致するノードがない場合、関数は nil を返します。
これは、複数のノードアクセサ関数を連結する便利な関数です。例えば、nodeの親の次の兄弟要素の2番目の子要素のテキストを取得するには：
(treesit-node-get node
'((parent 1)
(sibling 1 nil)
(child 1 nil)
(text nil)))
instruction は (fn arg...) 形式の
INSTRUCTION のリストです。以下の fn がサポートされています：
(child idx named)idx番目の子を取得します。
(parent n)親要素へ n 回移動する。
(field-name)現在のノードのフィールド名を取得します。
(type)現在のノードの型を取得します。
(text no-property)現在のノードのテキストを取得します。
(children named)子供の一覧を取得する。
(sibling step named)n番目の直前/直後の兄弟要素を取得します。負の値 step は直前の兄弟要素を、正の値は直後の兄弟要素を表します。
なお、namedやno-propertyといった引数は、元の関数とは異なり省略できない点に注意してください。
この関数は、node の直下の子要素のうち、predicate を満たすものを検索します。
predicate 関数はノードを引数として受け取り、そのノードを保持すべきことを示すために
non-nil を返す必要があります。named が
non-nil である場合、この関数は名前付きノードのみを検査します。
この関数はnodeの親を繰り返し探索し、predicateを満たす親を返します。predicateには、ノードを引数として受け取りtまたはnilを返す関数、ノードタイプ名にマッチする正規表現、あるいはtreesit-thing-settingsで記述されているその他の有効な述語を指定できます。predicatesを満たす親が存在しない場合、この関数はnilを返します。
通常、この関数はnodeの親のみを参照し、node自体は参照しません。ただし、include-nodeがnilでない場合、nodeがpredicateを満たすなら、この関数はnodeを返します。
この関数はnodeを起点としてツリーを遡り、ノードがノードを引数とする関数predicateを満たす限り、その処理を継続します。つまり、この関数はpredicateを依然として満たすnodeの最上位の親を返します。なお、nodeがpredicateを満たしていても、その直上の親が満たしていない場合は、node自体が返されます。
この関数は、node の最上位親のうち、node
と同じ型を持つものを返します。そのような親が存在しない場合は、nil
を返します。したがって、この関数は node がトップレベルであるかどうかを判定する際にも有用です。
predicate が nil の場合、この関数は
node の型を用いて親を特定します。predicate が
nil 以外の場合、この関数は predicate
を満たす親を検索します。include-node が nil 以外の場合、node が predicate を満たすなら、この関数は node を返します。