必要なパッケージは2つ
Python から tree-sitter を使うには、次の2つのパッケージを入れる。
| パッケージ | 役割 | 確認したバージョン |
|---|---|---|
tree-sitter | 本体(Parser・Tree・Node・Query)。py-tree-sitter とも呼ばれる | 0.26.0 |
tree-sitter-java | Java の文法(コンパイル済みのパーサー) | 0.23.5 |
どちらも Windows・macOS・Linux 向けのビルド済みパッケージ(wheel)が PyPI に公開されているので、C コンパイラや Visual Studio Build Tools は要らない。古い記事では「文法の Git リポジトリを clone して Language.build_library() でビルドする」手順が紹介されているが、この方法は 0.22 で廃止された。今は pip で入れるだけでよい。
仮想環境を作って導入する
解析用のフォルダを作り、その中に仮想環境を用意する。Python は 3.10 以上を使う。
mkdir C:\work\ts-java
cd C:\work\ts-java
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install tree-sitter tree-sitter-javaLinux / macOS / WSL なら次のとおり。
mkdir -p ~/work/ts-java && cd ~/work/ts-java
python3 -m venv .venv
source .venv/bin/activate
pip install tree-sitter tree-sitter-java入ったバージョンを確認しておく。
pip show tree-sitter tree-sitter-java | Select-String "Name|Version" # bash なら grep -E "Name|Version"Name: tree-sitter
Version: 0.26.0
Name: tree-sitter-java
Version: 0.23.5⚠️ Activate.ps1 が実行できないとき
「このシステムではスクリプトの実行が無効になっている」と表示されたら、PowerShell の実行ポリシーが原因だ。Set-ExecutionPolicy -Scope CurrentUser RemoteSigned を一度実行するか、仮想環境を有効化せずに .\.venv\Scripts\python.exe を直接呼べばよい。
最初のパース
まずは文字列で書いた Java を1つパースしてみる。hello.py として保存する。
import tree_sitter_java as tsjava
from tree_sitter import Language, Parser
JAVA = Language(tsjava.language())
parser = Parser(JAVA)
source = b"""
public class Hello {
public static void main(String[] args) {
System.out.println("Hello, tree-sitter!");
}
}
"""
tree = parser.parse(source)
root = tree.root_node
print(root.type) # ルートノードの種類
print(root.has_error) # 構文エラーがあるか
print(str(root)) # S式で構文木全体を表示python hello.pyprogram
False
(program (class_declaration (modifiers) name: (identifier) body: (class_body (method_declaration (modifiers) type: (void_type) name: (identifier) parameters: (formal_parameters (formal_parameter type: (array_type element: (type_identifier) dimensions: (dimensions)) name: (identifier))) body: (block (expression_statement (method_invocation object: (field_access object: (identifier) field: (identifier)) name: (identifier) arguments: (argument_list (string_literal (string_fragment))))))))))3行目の長い出力が、構文木を S 式(括弧の入れ子)で表したものだ。(class_declaration ... body: (class_body (method_declaration ... と読んでいくと、クラスの中にメソッドがあり、その中に System.out.println の呼び出し(method_invocation)がある、という構造がそのまま見えている。読み方は PART 03 で詳しく扱う。
コードの要点は3つだけだ。
Language(tsjava.language()):文法パッケージが持つ C のパーサーを、tree-sitter 本体が扱えるLanguageに包むParser(JAVA):Java 用のパーサーを作る。1つ作れば何ファイルでも使い回せるparser.parse(source):bytes を渡す。strは渡せない(理由は次の節)
💡 古い書き方との違い(0.21 以前)
ネット上には parser = Parser() のあと parser.set_language(JAVA) と書く例や、node.sexp() で S 式を出す例が多い。どちらも現在のバージョンでは使えない。言語は Parser(JAVA) のようにコンストラクタで渡し(後から変えるなら parser.language = JAVA)、S 式は str(node) で得る。このシリーズのコードはすべて 0.26 で動作を確認している。
なぜ bytes なのか
tree-sitter はソースを UTF-8 のバイト列 として扱う。ノードが持つ位置情報も、文字数ではなくバイト数で数えられている。
| 属性 | 中身 | 単位 |
|---|---|---|
node.start_byte / end_byte | ノードの開始・終了位置 | バイト |
node.start_point / end_point | (row, column) の組。row は0始まり | 行/バイトで数えた桁 |
node.text | ノードに対応するソースの部分 | bytes |
日本語は UTF-8 で1文字3バイトなので、start_point.column はエディタに表示される桁とずれることがある。行番号(row + 1)だけを使うぶんには困らないが、桁まで使うなら注意が要る。テキストが欲しいときは、元のソースを切り出すより node.text.decode("utf-8") を使うのが簡単で確実だ。
Shift_JIS のソースを読む
長く運用されている Java 資産は、ソースの文字コードが Shift_JIS(Windows の cp932)のことが珍しくない。このまま read_bytes() でパースすると、構文木自体は作れる が、日本語を含むノードの text を UTF-8 でデコードしたところで UnicodeDecodeError になる。
そこで、ファイルを読むときに文字コードをそろえる共通モジュールを作っておく。UTF-8 として読めればそのまま、読めなければ cp932 とみなして UTF-8 に変換する。PART 03 以降のスクリプトはすべてこのモジュールを使う。
"""シリーズ共通:Java 用の Parser と、ソースを読み込むヘルパー"""
from pathlib import Path
import tree_sitter_java as tsjava
from tree_sitter import Language, Parser
JAVA = Language(tsjava.language())
parser = Parser(JAVA)
def read_source(path):
"""UTF-8 で読めなければ Shift_JIS(cp932)とみなし、UTF-8 のバイト列にそろえる"""
raw = Path(path).read_bytes()
try:
raw.decode("utf-8")
return raw
except UnicodeDecodeError:
return raw.decode("cp932").encode("utf-8")
def parse_file(path):
src = read_source(path)
return src, parser.parse(src)
def text(node):
return node.text.decode("utf-8")Shift_JIS で保存した次のファイルで確かめる(中身は return "日本語"; を返すだけのクラス)。
python -c "from ts_common import parse_file, text; s, t = parse_file('sjis.java'); print(t.root_node.has_error, text(t.root_node))"False class S { String m() { return "日本語"; } }⚠️ 判定は「UTF-8 として読めるか」だけ
このやり方は、プロジェクトの中に UTF-8 と Shift_JIS が混在していても動くのが利点だ。一方で EUC-JP など第3の文字コードは想定していない。文字コードが分かっているなら、決め打ちで raw.decode("cp932") と書くほうが安全である。BOM 付き UTF-8 は、\ufeff が先頭に付くだけで解析には影響しない。
このシリーズで使うファイル
以降の回では、作業フォルダに次のファイルを置いていく。サンプルの Java ソースは PART 04・05 で全文を載せる。
C:\work\ts-java
├── .venv\
├── ts_common.py ← この回(共通モジュール)
├── hello.py ← この回
├── dump_tree.py ← PART 03(構文木の表示)
├── broken.py ← PART 03(エラーノード)
├── query_basic.py ← PART 04
├── query_predicate.py ← PART 04
├── extract_deps.py ← PART 05(依存の抽出 → JSONL)
├── to_mermaid.py ← PART 05(JSONL → Mermaid)
├── lint.py ← PART 06(コードチェッカー)
└── sample\src\main\java\com\example\
├── order\OrderService.java
└── web\OrderController.java✅ 次の記事では…
PART 03 では、tree-sitter が返す構文木を1ノードずつ表示するスクリプトを作り、ノード型・フィールド名・名前なしノード、そして構文エラーのときに現れる ERROR / MISSING ノードを実物で確認する。