必要なパッケージは2つ

Python から tree-sitter を使うには、次の2つのパッケージを入れる。

パッケージ役割確認したバージョン
tree-sitter本体(Parser・Tree・Node・Query)。py-tree-sitter とも呼ばれる0.26.0
tree-sitter-javaJava の文法(コンパイル済みのパーサー)0.23.5

どちらも Windows・macOS・Linux 向けのビルド済みパッケージ(wheel)が PyPI に公開されているので、C コンパイラや Visual Studio Build Tools は要らない。古い記事では「文法の Git リポジトリを clone して Language.build_library() でビルドする」手順が紹介されているが、この方法は 0.22 で廃止された。今は pip で入れるだけでよい。

仮想環境を作って導入する

解析用のフォルダを作り、その中に仮想環境を用意する。Python は 3.10 以上を使う。

PowerShell
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-java

Linux / macOS / WSL なら次のとおり。

bash
mkdir -p ~/work/ts-java && cd ~/work/ts-java
python3 -m venv .venv
source .venv/bin/activate
pip install tree-sitter tree-sitter-java

入ったバージョンを確認しておく。

PowerShell / bash
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 として保存する。

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式で構文木全体を表示
PowerShell / bash
python hello.py
実行結果
program
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つだけだ。

  1. Language(tsjava.language()):文法パッケージが持つ C のパーサーを、tree-sitter 本体が扱える Language に包む
  2. Parser(JAVA):Java 用のパーサーを作る。1つ作れば何ファイルでも使い回せる
  3. 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 以降のスクリプトはすべてこのモジュールを使う。

ts_common.py
"""シリーズ共通: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 "日本語"; を返すだけのクラス)。

PowerShell / bash
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 ノードを実物で確認する。

→ PART 03 — 構文木の構造を読むへ