このセクションではtree-sitterパーサーをどのようにして作成して構成するかについて説明します。Emacsにおけるtree-sitterパーサーはそれぞれバッファーに関連付けられます。ユーザーによるバッファーの編集にしたがって、関連付けられているパーサーと構文ツリーは自動的に最新に保たれるのです。
この変数にはtree-sitterをアクティブにし得るバッファーの最大サイズが含まれる。メジャーモードはtree-sitter機能を有効にするかどうかを判断する際にはこの変数をチェックすること。
指定されたbufferおよびlanguage (Tree-sitter言語グラマーを参照)にたいして、tagとしてパーサーを作成する。バッファーが省略またはnilの場合にはカレントバッファーを意味する。
この関数はbufferのlanguageにたいするtagというパーサーがすでに存在していれば、デフォルトではそれを再利用するがno-reuseが非nilの場合には常に新たなパーサーを作成する。
tagはtを除く任意のシンボルで、デフォルトはnil。異なるパーサーが同じタグを保有し得る。
そのバッファーがインダイレクトバッファーなら、かわりにベースバッファーを使用する。つまりインダイレクトバッファーではそのベースバッファーのパーサーが使用される。ベースバッファーがナローイングされていると、インダイレクトバッファーがベースバッファーで不可視なバッファーテキスト部分の情報を取得できないかもしれない。Lispプログラムがインダイレクトバッファーでパーサーを使用するためには、必要に応じてwiden(訳注: カレントバッファーからナローイングによる制限を取り去る関数)する必要がある。
パーサーが与えられれば、それに関する情報を問い合わせることができます。
この関数はparserに関連付けられているバッファーをリターンする。
この関数はparserが使用する言語をリターンする。
この関数はobjectをチェックしてtree-sitterパーサーなら非nil、そうでなければnilをリターンする。
パースは自動的かつ遅延して行われるので、明示的にバッファーをパースする必要はありません。パーサーがパースを行うのは、Lispプログラムがパーサーの構文ツリーのノードにたいして問い合わせを行ったときだけです。したがって最初にパーサーが作成された際にはバッファーのパースは行われず、Lispプログラムがノードにたいする問い合わせを最初に行うまで待機します。同様に何らかの変更をバッファーに行った際にも、パーサーが即座に再パースする訳ではありません。
パーサーがパースを行う際にはバッファーのサイズをチェックします。tree-sitterが処理できるのはおよそ4GBまでです。サイズがそれを超えると、Emacsはそのバッファーサイズをシグナルデータとしてtreesit-buffer-too-largeエラーをシグナルするでしょう。
一度パーサーを作成すると、Emacsが自動的にそれを内部のパーサーリストに追加します。バッファーにたいして変更が行われるたびに、パーサーがインクリメンタルに構文ツリーを更新できるように、Emacsがこのリストにあるパーサーを更新するのです。
この関数はlanguageとtagで絞り込んだbufferのパーサーリストをリターンする。bufferがnilまたは省略の場合のデフォルトはカレントバッファー。そのバッファーがインダイレクトバッファーなら、かわりにベースバッファーを使用する。つまりインダイレクトバッファーではそのベースバッファーのパーサーが使用される。
languageが非nilならその言語にたいするパーサーでtagというパーサーのみが含まれる。tagのデフォルトはnil。nilがtならリターンされるリストには含まれるパーサーはすべてのタグが含まれる。
この関数はparserを削除する。
パーサーは通常はバッファー全体を“見ている”ものですが、バッファーがナローイング(ナローイングを参照)されているとパーサーが見るのはバッファーのアクセス可能範囲だけになります。パーサーが見る限りでは、隠されているリージョンは削除されたことになります。後刻バッファーがワイドニングされた際には、先頭と終端にテキストが挿入されたとパーサーは考えるでしょう。パーサーがナローイングを尊重するにしても、複数言語のバッファーを処理するという意味合いでモードはナローイングを使用するべきではありません。そのかわりにパーサーが処理する必要がある範囲をセットするべきです。複数言語のパースを参照してください。
パーサーはパースを遅延させるので、ユーザーやLispプログラムがバッファーをナローイングしてもパーサーはすぐに影響を受けないのです。バッファーをナローイングしていても、モードがノードについて問い合わせをするまでパーサーはナローイングを認識しません。
バッファーにたいしてパーサーを作成するだけではなく、Lispプログラムが文字列のパースを行うことも可能です。バッファーと違い文字列のパースは一度かぎりの操作であり、結果を更新する手段はありません。
この関数はlanguageを使用してstringのパースを行い、生成された構文ツリーのルートノードをリターンする。
Lispプログラムはインクリメンタルなパースによって影響を受けるテキストにたいして通知してほしい場合があるかもしれません。たとえばコメントを閉じるtokenの挿入によって、そのtokenの手前にあるテキストを変換する場合です。たとえテキストが直接変更されなくても、それは“変更”とみなされるのです。
Emacsではこれらの類いの変更にたいして、Lispプログラムにコールバック関数(別名notifier)を登録できます。notifier関数はranges、parserという2つの引数を受け取ります。rangesは(start . end)という形式をもつコンスセルのリストです。ここでstart、endは範囲の開始と終了をマークします。parserは通知を発行するパーサーです。
パーサーはバッファーを再パースするたびに構文ツリーの新旧を比較して、変更されたノード範囲の計算を行いその範囲をnotifier関数に引き渡します。最初のパースも“変更”とみなされるので、最初のパースではバッファー全体を範囲としてnotifier関数が呼び出されることに注意してください。
この関数はparserのnotifier関数のafter-changeリストにfunctionを追加する。functionはlambda関数ではなく、関数シンボルでなければならない(無名関数を参照)。
この関数はparserのnotifier関数のafter-changeリストからfunctionを削除する。functionはlambda関数ではなく、関数シンボルでなければならない(無名関数を参照)。
この関数はparserのnotifier関数のリストをリターンする。