S 式の読み方

PART 02 で str(root) が出した S 式を、短いクラスで読み直してみる。次の small.java を用意する。

small.java
public class Calc {
    private int total = 0;
    public int add(int x) {
        total += x;
        return total;
    }
}

このメソッド add の部分だけを S 式で見ると、次のようになる(読みやすいように改行を入れた)。

S 式(method_declaration 部分)
(method_declaration
  (modifiers)
  type: (integral_type)
  name: (identifier)
  parameters: (formal_parameters
    (formal_parameter
      type: (integral_type)
      name: (identifier)))
  body: (block
    (expression_statement
      (assignment_expression
        left: (identifier)
        right: (identifier)))
    (return_statement
      (identifier))))
  • 括弧1組が1ノード。括弧の先頭の単語がノード型(method_declaration)
  • name: のような接頭辞がフィールド名。親から見たときの子の役割を表す
  • S 式には 名前付きノードだけ が出る。public・(・; のような記号は省略されている
method_declarationの子としてmodifiers、type: integral_type、name: identifier、parameters: formal_parameters、body: blockがあり、formal_parametersの下にformal_parameter、blockの下にexpression_statementとreturn_statementがある構文木の図

図1: S 式を木の形に描いたもの。斜体がフィールド名

名前付きノードと名前なしノード

tree-sitter のノードには2種類ある。

名前付きノード(named)名前なしノード(anonymous)
例method_declaration、identifier、blockpublic、int、(、{、;、+=
文法での定義規則(rule)として名前が付いている文法の中に文字列として直接書かれている
node.is_namedTrueFalse
取り出し方node.named_children、node.named_child_countnode.children には両方が含まれる

解析で使うのはほとんど名前付きノードだ。ただし、modifiers の中の public や static、代入演算子が = か += か、といった情報は名前なしノードとして入っているので、必要なときは node.children を見る。

Python
mods = method.children[0]              # modifiers
print([c.type for c in mods.children])  # ['public']  ← 名前なしノード
print(mods.named_child_count)           # 0(アノテーションがあればそれが名前付きで入る)

フィールドで子を取り出す

「メソッドの名前」を取りたいとき、子を順番に数えて children[2] のように取るのは危険だ。修飾子やアノテーション、型パラメーター(<T>)の有無で位置がずれる。代わりに フィールド名 を使う。

Python
name = method.child_by_field_name("name")        # identifier
body = method.child_by_field_name("body")        # block(abstract メソッドなら None)
params = method.child_by_field_name("parameters")
print(name.text.decode(), name.start_point.row + 1)

Java の文法でよく使うノード型とフィールドを表にしておく。完全な一覧は tree-sitter-java の src/node-types.json に定義されている。

ノード型主なフィールド対応する Java の構文
class_declarationname、superclass、interfaces、bodyclass A extends B implements C { }
interface_declaration / enum_declaration / record_declarationname、bodyインターフェース・列挙型・レコード
method_declarationtype、name、parameters、bodyメソッド
constructor_declarationname、parameters、bodyコンストラクタ(type はない)
field_declarationtype、declarator(variable_declarator)private int total = 0;
local_variable_declarationtype、declaratorメソッド内の変数宣言
method_invocationobject、name、argumentsrepo.save(order)
object_creation_expressiontype、argumentsnew Order(id)
if_statementcondition、consequence、alternativeif (...) { } else { }
catch_clausebodycatch (Exception e) { }

💡 field_declaration の名前は1段深い

Java では int a, b; のように1つの宣言で複数の変数を書けるため、フィールド名は field_declaration の直下ではなく、declarator:(variable_declarator)の name: にある。メソッドと同じつもりで child_by_field_name("name") を呼ぶと None が返るので注意する。

構文木を全部表示するスクリプト

ノード名を調べるには、実際のソースの木を全部表示してしまうのが早い。TreeCursor を使って木を深さ優先でたどり、名前付きノードをインデント付きで出すスクリプトを作る。

dump_tree.py
import sys
from ts_common import parse_file

def dump(cursor, depth=0):
    node = cursor.node
    field = cursor.field_name
    label = f"{field}: " if field else ""
    pos = f"[{node.start_point.row + 1}:{node.start_point.column}]"
    if node.is_named:
        snippet = ""
        if node.named_child_count == 0:
            snippet = "  " + repr(node.text.decode("utf-8"))
        print(f"{'  ' * depth}{label}{node.type} {pos}{snippet}")
    if cursor.goto_first_child():
        while True:
            dump(cursor, depth + 1)
            if not cursor.goto_next_sibling():
                break
        cursor.goto_parent()

src, tree = parse_file(sys.argv[1])
dump(tree.walk())
PowerShell / bash
python dump_tree.py small.java
実行結果
program [1:0]
  class_declaration [1:0]
    modifiers [1:0]  'public'
    name: identifier [1:13]  'Calc'
    body: class_body [1:18]
      field_declaration [2:4]
        modifiers [2:4]  'private'
        type: integral_type [2:12]  'int'
        declarator: variable_declarator [2:16]
          name: identifier [2:16]  'total'
          value: decimal_integer_literal [2:24]  '0'
      method_declaration [3:4]
        modifiers [3:4]  'public'
        type: integral_type [3:11]  'int'
        name: identifier [3:15]  'add'
        parameters: formal_parameters [3:18]
          formal_parameter [3:19]
            type: integral_type [3:19]  'int'
            name: identifier [3:23]  'x'
        body: block [3:26]
          expression_statement [4:8]
            assignment_expression [4:8]
              left: identifier [4:8]  'total'
              right: identifier [4:17]  'x'
          return_statement [5:8]
            identifier [5:15]  'total'

[行:桁] は1始まりの行番号と0始まりの桁、末尾の '...' は子に名前付きノードを持たないノードのテキストだ。modifiers [1:0] 'public' のように、名前なしノードしか持たないノードもテキストが表示されるので、記号の中身もここで確認できる。

✅ TreeCursor を使う理由

node.children を再帰でたどっても同じ結果になるが、children は呼ぶたびに子ノードのオブジェクトを作る。TreeCursor は1つのカーソルを動かすだけなので、大きなファイルでも速くメモリを食わない。また cursor.field_name で「今いるノードが親のどのフィールドか」がわかるのも便利な点だ。

構文エラーがあるときの木

tree-sitter の大きな特徴が、構文エラーがあっても解析を止めないことだ。わざと壊したメソッドを含むソースで確かめる。

broken.py
from ts_common import parser

source = b"""
public class Broken {
    public void ok() { System.out.println("ok"); }
    public void ng( { int x = ; }
    public void after() { run(); }
}
"""
tree = parser.parse(source)
print("has_error:", tree.root_node.has_error)

def find_problems(node):
    if node.is_error or node.is_missing:
        kind = "MISSING" if node.is_missing else "ERROR"
        print(f"{kind} {node.type!r} at line {node.start_point.row + 1}")
    for child in node.children:
        find_problems(child)

find_problems(tree.root_node)

# エラーがあっても後続のメソッドは取れる
for m in tree.root_node.named_children[0].child_by_field_name("body").named_children:
    if m.type == "method_declaration":
        print("method:", m.child_by_field_name("name").text.decode())
実行結果
has_error: True
MISSING ')' at line 4
ERROR 'ERROR' at line 4
method: ok
method: ng
method: after

壊れた箇所には2種類のノードが現れる。

ノード判定意味
ERRORnode.is_errorどの規則にも当てはめられなかった部分をまとめたもの
MISSINGnode.is_missing本来あるべきトークン(ここでは ))をパーサーが補ったもの。長さ0のノード

注目したいのは最後の3行だ。ng が壊れていても、その後ろの after まで method_declaration として正しく取れている。コンパイルが通らない作業途中のソースや、一部だけ切り出したソースを調べられるのは、この性質のおかげである。

⚠️ エラーの「位置」は目安

パーサーはエラーを最小限の変更で回復しようとするため、ERROR ノードが実際の原因より前後にずれることがある。解析ツールでは root_node.has_error を見て「このファイルの結果は参考値」と印を付けるくらいにとどめ、エラーの位置を厳密に信じないほうがよい(PART 06 のチェッカーもそうしている)。

ノード名を調べるコツ

  • 調べたい構文だけの小さなファイルを作る:実際のソースを丸ごと表示すると長すぎて追えない。dump_tree.py に5〜10行のファイルを渡すのが一番早い
  • 公式サイトの Playground を使う:コードを貼るだけで木が見え、ノードをクリックするとソースの対応箇所がハイライトされる
  • node-types.json を引く:あるノード型がどんなフィールドと子を持ちうるかは、tree-sitter-java リポジトリの src/node-types.json がいちばん正確

✅ 次の記事では…

PART 04 では、木を自分でたどる代わりに、Query(S 式パターン)で「メソッド宣言の名前」「System.out.println の呼び出し」のような構造をまとめて取り出す。

→ PART 04 — Query による抽出へ