以下はわたしたちがtree-sitter関数を文書化する際に用いる用語と慣習についてです。
構文ツリーのノードは、バッファーのプログラムテキストのある部分に跨ります(span)。あるノードの跨ぐバッファーテキスト部分が、他のノードのそれより小さい(または大きい)場合には、わたしたちはそのノードが他のノードより“小さい”(または“大きい”)と表現します。ツリーにおいてより深い(“下位”の)ノードは、そのツリーのより“上位”ノードの子となるので、そのノード階層において下位のノードは常に上位のノードより小さくなります。構文ツリーの上位のノードには、その子として1つ以上の小さいノードが含まれており、したがってバッファーテキストのより大きい部分を跨ぐことになるのです。
関数がノードを見つけられなかった場合にはnilをリターンします。利便性のために、引数としてノードを受け取ってノードをリターンするすべての関数もnilの引数を許し、そのような場合には単にnilをリターンするようになっています。
関連付けられているバッファーが更新された際にノードが自動的に更新されることはなく、一度取得したノードを更新する術は存在しません。古くなってしまったノードを使用するとtreesit-node-outdatedエラーがシグナルされるでしょう。
この関数はバッファー位置posにある葉ノード(leaf node)をリターンする。葉ノードとは子ノードを何ももたないノードのこと。
この関数はposを跨がって覆う(cover)ようなノードのリターンを試みる。これは開始位置が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の場合には、この関数は名前つきのノードだけを探す(named nodeを参照)。
例:
;; Cパーサーの構文ツリーでポイント位置のノードを探す (treesit-node-at (point) 'c) ⇒ #<treesit-node (primitive_type) in 23-27>
この関数はbegとendの間にあるバッファーテキストのリージョンを覆うような、もっとも小さいノードをリターンする。言い換えると開始がbeg以前、かつ終了がend以降であるようなノードのこと。
注意せよ:
トップレベル構文(関数定義等)の内部ではない空行でこの関数を呼び出すと、恐らくルートノードが取得される場合がほとんどだろう。その空行を覆うもっとも小さいノードがルートノードだというのがその理由だが、あなたが使いたいと望んでいる機能は、ほとんどの場合はtreesit-node-atのほうだろう。
parser-or-langがパーサーオブジェクトなら、この関数はそのパーサーを使用する。parser-or-langが言語の場合には、この関数はカレントバッファーにおいてその言語用の最初のパーサー、もし存在しなければパーサーを作成してそれを使用する。parser-or-langがnilなら、この関数はtreesit-language-at
(複数言語のパースを参照)を呼び出して、begの言語の推測を試みる。
namedが非nilの場合には、この関数は名前つきのノードだけを探す(named nodeを参照)。
この関数はparserが生成した構文ツリーのルートノードをリターンする。
この関数はカレントバッファーでlanguage用の最初のパーサー、パーサーが存在しなければ作成して、そのパーサーが生成したルートノードをリターンする。languageが省略された場合にはパーサーリストの最初のパーサーを使用する。適切なパーサーが見つからなければnilをリターンする。
Lispプログラムはノードが与えられれば、そこから始まる他のノードを取得したり、そのノードに関する情報を問い合わせることができます。
この関数はnodeの直近の親をリターンする。
パースツリー(parse tree:
解析木)においてnodeが1000を超える深さのレベルにある場合のリターン値は未定義。現在のところnilをリターンするが、将来変更されるかもしれない。
この関数はnodeのn番目の子をリターンする。namedが非nilなら名前つきのノードだけを考慮する(named nodeを参照)。
たとえば文字列"text"を表すノードの場合には開クォート"、文字列テキストのtext、それに閉クォート"という3つの子ノードが存在する。これら3つのノードの中で最初の子は開クォート"、最初の名前つきの子は文字列テキストとなる。
この関数はn番目の子が存在しなければnilをリターンする。nは負でも可(−1は最後の子を表す)。
この関数はnodeのすべての子をリストでリターンする。namedが非nilなら名前つきのノードだけを取得する。
この関数はnodeの次の兄弟を探す。namedが非nilなら次の名前つきの兄弟を探す。
この関数はnodeの前の兄弟を探す。namedが非nilなら前の名前つきの兄弟を探す。
構文ツリーの分析をより容易にするために、多くの言語ではグラマーで子ノードにフィールド名(field
names)を割り当てています(field
nameを参照)。たとえばfunction_definitionノードにはdeclaratorやbodyという子ノードがあるかもしれません。
この関数はフィールド名がfield-name(文字列)であるようなnodeの子を探す。
;; フィールド名が"body"という子を取得 (treesit-node-child-by-field-name node "body") ⇒ #<treesit-node (compound_statement) in 45-89>
この関数はバッファー位置posを超えて広がるようなnodeの最初の子をリターンする。“超えて広がる(extends
beyond)”とは子ノードの終端がpos以降であることを意味する。この関数はnodeの直接の子だけを調べる(孫は調べない)。namedが非nilの場合には最初の名前つきの子を探す(named nodeを参照)。
これは位置begとendの間にあるテキストリージョンを跨ぐような、もっとも小さいnodeの子孫ノードを探す、treesit-node-atと似た関数。namedが非nilの場合には、もっとも小さい名前つきの子を探す。
この関数はnodeのサブツリー(node自体を含む)を横断(traverse)して、predicateが非nilをリターンするようなノードを探す。predicateはノードそれぞれのタイプにたいしてマッチさせるregexp、あるいはノードを受け取りそのノードがマッチしたら非nilをリターンするような述語関数。predicateはthingシンボルかthing定義でもよい(ユーザー定義の“Things”とナビゲーションを参照)。未定義のthingを使用してもエラーは起こらず、この関数は単にnilをリターンする。
この関数はpredicateにマッチした最初のノード、マッチがなければnilをリターンする。
この関数が検索するのはデフォルトでは名前つきノードだけだが、allが非nilならすべてのノードを横断して検索を行う。backwardが非nilの場合には後方に横断して検索する(ツリーを下降して横断していく際に最後の子を最初に調べる)。depthが非nilなら、それはツリーを横断して下降できるレベル数を制限する数値でなければならない。depthがnilの場合のデフォルトは1000。
この関数は(startを除けば)treesit-search-subtreeと同じようにパースツリーを横断して、predicateによりそれぞれのノードをマッチする(predicateはregexpまたは述語関数)。predicateはthingシンボル、あるいはthing定義でもよい(ユーザー定義の“Things”とナビゲーションを参照)。未定義のthingを使用してもエラーは起こらず、関数は単にnilをリターンする。
以下のようなツリー(‘S’マークはstart)の場合には、この関数は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の後にあり何らかの条件を満足する最初のノードはどれ?”、のような問いの答えを求めるのに役に立つ。
この関数はバッファーでnodeの後にありpredicateにマッチする次のノードの開始または終了にポイントを移動する。startが非nilなら、ノードの終了ではなく開始で停止する。
この関数がリターンするマッチしたノードは、バッファー位置という点において進行方向にある(リターンされたノードの開始/終了はnodeのそれより常に大きい)ことが保証されている。
引数predicate、backward、allはtreesit-search-forwardの場合と同じ。
この関数はrootのサブツリーからsparseツリー(疎らなツリー)を作成する。
この関数はroot配下のサブツリーを受け取って、predicateにマッチするノードだけが残るように間引く。前の関数と同じようにpredicateはノードそれぞれのタイプにマッチさせるためのregexp文字列、またはノードを受け取ってマッチした場合には非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に渡してリターン値を使用する。depthが非nilなら、それは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)指定した個数分前または後の兄弟を取得。負のstepは前の兄弟、正なら後の兄弟を意味する。
元となる関数とは異なり、namedやno-propertyのような引数は省略できないことに注意。
この関数はpredicateを満足するnodeの直接の子を探す。
predicateは引数としてノードを受け取り、そのノードを候補に残すべきなら非nilをリターンする関数であること。namedが非nilなら、この関数は名前つきのノードだけを調べる。
この関数はnodeの親を順繰りに探して、predicateを満足する親をリターンする。predicateには引数としてノードを受け取りtかnilをリターンする関数、ノードのタイプ名にマッチするregexp、あるいはtreesit-thing-settingsに記述されているその他有効な述語のいずれかを指定できる。predicatesを満足する親か存在しなければ、この関数はnilをリターンする。
この関数は通常だとnode自体ではなくnodeの親だけを調べる。しかし、include-nodeが非nilの場合には、nodeがpredicateを満足すればnodeをリターンする。
この関数はnodeを開始点としてノードがpredicate (引数としてノードを受け取る関数)を満足するかぎりツリーを上方に移動する。つまりこの関数はpredicateを満足するもっとも高位にあるnodeの親をリターンする。nodeがpredを満足して、かつ直近の親はpredicateを満足しなければ、node自体がリターンされることに注意。
この関数はnodeと同じタイプをもつ、もっとも高くにある親をリターンする。そのような親がいなければnilをリターンする。したがってこの関数はnodeがトップレベルかどうかをテストするためにも役に立つ。
この関数はpredicateがnilならnodeのタイプを用いて親を探し、predicateが非nilならpredicateを満足する親を検索する。include-nodeが非nilの場合には、この関数はpredicateを満足するnodeをリターンする。