Next: ノード情報へのアクセス, Previous: tree-sitterパーサーの使用, Up: プログラムソースの解析 [Contents][Index]
以下はわたしたちが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
をリターンするような述語関数。この関数はマッチした最初のノード、何もマッチしなければnil
をリターンする。
この関数が検索するのはデフォルトでは名前つきノードだけだが、allが非nil
ならすべてのノードを横断して検索を行う。backwardが非nil
の場合には後方に横断して検索する(ツリーを下降して横断していく際に最後の子を最初に調べる)。depthが非nil
なら、それはツリーを横断して下降できるレベル数を制限する数値でなければならない。depthがnil
の場合のデフォルトは1000。
この関数は(startを除けば)treesit-search-subtree
と同じようにパースツリーを横断して、predicateによりそれぞれのノードをマッチする(predicateはregexpまたは関数)。以下のようなツリー(‘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でリターンされるのが右側のツリー。
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
をリターンする。
この関数はpredicateを満足するnodeの直接の子を探す。
predicateは引数としてノードを受け取り、そのノードを候補に残すべきなら非nil
をリターンする関数であること。namedが非nil
なら、この関数は名前つきのノードだけを調べる。
この関数はnodeの親を順繰りに探して、pred
(引数としてノードを受け取りマッチを示すブーリーン値をリターンする関数)を満足する親をリターンする。predを満足する親がいなければ、この関数はnil
をリターンする。
この関数は通常だとnode自体ではなくnodeの親だけを調べる。しかし、include-nodeが非nil
の場合には、nodeがpredを満足すればnodeをリターンする。
この関数はnodeを開始点としてノードがpred (引数としてノードを受け取る関数)を満足するかぎりツリーを上方に移動する。つまりこの関数はpredを満足するもっとも高位にあるnodeの親をリターンする。nodeがpredを満足して、かつ直近の親はpredを満足しなければ、node自体がリターンされることに注意。
この関数はnodeと同じタイプをもつ、もっとも高くにある親をリターンする。そのような親がいなければnil
をリターンする。したがってこの関数はnodeがトップレベルかどうかをテストするためにも役に立つ。
typeが非nil
の場合には、この関数はnodeのタイプではなく、regexpとしてtypeを用いてそれぞれの親のタイプをマッチする。
Next: ノード情報へのアクセス, Previous: tree-sitterパーサーの使用, Up: プログラムソースの解析 [Contents][Index]