この回から使うサンプル
PART 04〜06 では、Spring Boot 風の注文サービスを解析対象にする。わざと「空の catch」や「System.out.println」を入れてあるので、PART 06 のチェッカーで引っかかるようになっている。
package com.example.order;
import java.util.List;
import java.util.ArrayList;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
public class OrderService {
private final OrderRepository repository;
private final MailSender mailSender;
public OrderService(OrderRepository repository, MailSender mailSender) {
this.repository = repository;
this.mailSender = mailSender;
}
@Transactional
public Order placeOrder(String customerId, List<Item> items) {
Order order = new Order(customerId);
for (Item item : items) {
if (item.getQuantity() > 0) {
if (item.isInStock()) {
order.addItem(item);
} else {
System.out.println("在庫切れ: " + item.getName());
}
}
}
repository.save(order);
try {
mailSender.send(customerId, "ご注文ありがとうございます");
} catch (Exception e) {
}
return order;
}
public List<Order> findOrders(String customerId) {
return repository.findByCustomerId(customerId);
}
}Query の基本形
Query は、PART 03 で見た S 式と同じ形で書く。取り出したいノードの後ろに @名前 を付けると、そのノードが キャプチャ として返ってくる。
(method_declaration
name: (identifier) @method.name)これは「method_declaration で、name フィールドが identifier のもの」に一致し、その identifier を method.name という名前で返す、という意味になる。パターンに書かなかった子(修飾子や本体)は、あってもなくても一致する。
クラス名・メソッド・フィールドをまとめて取り出すスクリプトを書いてみる。
import sys
from tree_sitter import Query, QueryCursor
from ts_common import JAVA, parse_file, text
QUERY = Query(JAVA, r"""
(class_declaration
name: (identifier) @class.name)
(method_declaration
type: (_) @method.return
name: (identifier) @method.name
parameters: (formal_parameters) @method.params)
(field_declaration
type: (_) @field.type
declarator: (variable_declarator
name: (identifier) @field.name))
""")
src, tree = parse_file(sys.argv[1])
cursor = QueryCursor(QUERY)
# captures(): キャプチャ名ごとにノードの一覧が返る
captures = cursor.captures(tree.root_node)
for name in ("class.name", "method.name", "field.name"):
print(name, [text(n) for n in captures.get(name, [])])
print("---")
# matches(): 1つのパターンに一致した組をまとめて返す
for pattern_index, m in cursor.matches(tree.root_node):
if pattern_index == 1:
print(f"method {text(m['method.name'][0])}"
f"{text(m['method.params'][0])} -> {text(m['method.return'][0])}")
elif pattern_index == 2:
print(f"field {text(m['field.name'][0])} : {text(m['field.type'][0])}")python query_basic.py sample/src/main/java/com/example/order/OrderService.javaclass.name ['OrderService']
method.name ['placeOrder', 'findOrders']
field.name ['repository', 'mailSender']
---
field repository : OrderRepository
field mailSender : MailSender
method placeOrder(String customerId, List<Item> items) -> Order
method findOrders(String customerId) -> List<Order>3つのパターンを1つの Query にまとめて書けること、type: (_) の (_) が「どんな名前付きノードでもよい」というワイルドカードであることがポイントだ。戻り値の型は integral_type のときも generic_type(List<Order>)のときもあるので、ワイルドカードで受けている。
💡 コンストラクタが出てこない理由
出力にコンストラクタ OrderService(...) がないのは、Java の文法ではコンストラクタが method_declaration ではなく constructor_declaration という別のノード型だからだ。両方を取りたいときは次の節の「選択」[ ] を使う。
captures と matches の違い
Query を実行するのは QueryCursor で、結果の受け取り方が2通りある。
| メソッド | 戻り値 | 向いている用途 |
|---|---|---|
captures(node) | {キャプチャ名: [Node, ...]} の辞書。ノードはソース上の位置順 | 「メソッド名を全部」のように、キャプチャを1種類ずつ使う |
matches(node) | [(パターン番号, {キャプチャ名: [Node, ...]}), ...] のリスト | 「メソッド名と、その引数と戻り値」のように、同じ一致に属する複数のキャプチャを組で使う |
captures() では、method.name の一覧と method.params の一覧が別々に返ってくるので、どの名前とどの引数が組なのかは自分で位置を比べないとわからない。matches() なら1件の一致ごとに辞書が返るので組がずれない。パターン番号(0始まり)は Query の中でパターンを書いた順番で、上の例では 1 がメソッド、2 がフィールドに当たる。
⚠️ 0.25 で API が変わった
0.24 以前は query.captures(node) のように Query 自体にメソッドがあった。0.25 からは QueryCursor(query).captures(node) に移っている。ネットの古いサンプルが AttributeError になる場合は、ここを疑う。
パターンの書き方
実務でよく使う書き方を表にまとめる。
| 書き方 | 意味 | 例 |
|---|---|---|
(_) | 任意の名前付きノード | type: (_) @t |
_ | 任意のノード(名前なしノードも含む) | (binary_expression operator: _ @op) |
"文字列" | 名前なしノード(記号・キーワード) | (assignment_expression operator: "+=") |
[ A B ] | 選択(A または B) | [(method_declaration) (constructor_declaration)] @m |
? / * / + | 0か1回/0回以上/1回以上 | object: (_)? @obj |
. | アンカー(最初の子・最後の子・隣接) | (class_body . (field_declaration) @first) |
!field | そのフィールドを持たない | (method_declaration !body) = 本体のない abstract メソッド |
; コメント | Query 内のコメント | ; System.out の呼び出し |
たとえばメソッドとコンストラクタの名前を両方取るなら、選択を使って次のように書ける。
[
(method_declaration name: (identifier) @name)
(constructor_declaration name: (identifier) @name)
]['OrderService', 'placeOrder', 'findOrders']述語で絞り込む
形だけでなく「名前が System のもの」のようにテキストで絞り込みたいときは、パターンの後ろに 述語 を書く。述語を付けるときは、パターン全体をもう1組の括弧で囲む。
| 述語 | 意味 |
|---|---|
(#eq? @a "文字列") / (#eq? @a @b) | テキストが一致する(キャプチャ同士の比較もできる) |
(#not-eq? @a "文字列") | 一致しない |
(#match? @a "正規表現") | 正規表現に一致する(部分一致。全体一致させるなら ^...$) |
(#not-match? @a "正規表現") | 正規表現に一致しない |
(#any-of? @a "x" "y" ...) | いずれかと一致する |
System.out.println の呼び出し・@Transactional 付きのメソッド・find で始まるメソッドを探す例だ。
import sys
from tree_sitter import Query, QueryCursor
from ts_common import JAVA, parse_file, text
QUERY = Query(JAVA, r"""
; System.out.println(...) の呼び出し
((method_invocation
object: (field_access
object: (identifier) @_sys
field: (identifier) @_out)
name: (identifier) @_m) @println
(#eq? @_sys "System")
(#eq? @_out "out")
(#match? @_m "^print(ln)?$"))
; @Transactional が付いたメソッド
(method_declaration
(modifiers
(marker_annotation name: (identifier) @_ann))
name: (identifier) @tx.method
(#eq? @_ann "Transactional"))
; find で始まるメソッド
((method_declaration name: (identifier) @finder)
(#match? @finder "^find"))
""")
src, tree = parse_file(sys.argv[1])
caps = QueryCursor(QUERY).captures(tree.root_node)
for n in caps.get("println", []):
print(f"println line {n.start_point.row + 1}: {text(n)}")
for n in caps.get("tx.method", []):
print("transactional:", text(n))
for n in caps.get("finder", []):
print("finder:", text(n))println line 27: System.out.println("在庫切れ: " + item.getName())
transactional: placeOrder
finder: findOrdersSystem.out.println(...)は、objectがfield_access(System.out)、nameがprintlnのmethod_invocationになっている。@printlnは呼び出し全体に付けたキャプチャなので、出力には引数まで含めた全体が出る- 引数なしのアノテーション
@Transactionalはmarker_annotation、引数付きの@GetMapping("/x")はannotationという別のノード型になる。両方を見たいなら[(marker_annotation) (annotation)]と選択で書く - 述語の判定のためだけに使うキャプチャには、
@_sysのように_を付けて区別しておくと読みやすい(結果の辞書には含まれるので、使わずに無視する)
💡 grep との違いをもう一度
この Query は、コメントや文字列リテラルの中に System.out.println と書かれていても一致しない。System .out. println(...) のように空白や改行が入っていても一致する。PART 01 で挙げた grep の弱点が、構文木を相手にすることで自然に消えている。
Query のエラーと確かめ方
Query の文法が間違っていたり、文法に存在しないノード型・フィールド名を書いたりすると、Query(...) を作った時点で QueryError になる。位置まで教えてくれるので、typo はすぐ見つかる。
Query(JAVA, "(method_declaration nme: (identifier))")QueryError: Invalid field name at row 0, column 20: nmeノードの親子関係が文法上ありえない Query も、作成時に Impossible pattern として弾かれる。たとえば (field_declaration name: (identifier)) は、PART 03 で見たように名前が declarator の下にあるのでエラーになる。
やっかいなのは、文法上はありうるが、実際の木とは形が違う Query だ。これはエラーにならず、ただ0件になる。たとえば System.out.println を探すつもりで ((method_invocation object: (identifier) name: (identifier) @n) (#eq? @n "println")) と書くと、object は identifier ではなく field_access(System.out)なので1件も一致しない。結果が空だったら、まず dump_tree.py で実物の木を確認するのが近道だ。
✅ Query は別ファイルに置いてもよい
パターンが増えてきたら、queries/java_calls.scm のような .scm ファイルに分け、Query(JAVA, Path("queries/java_calls.scm").read_text()) で読み込むと管理しやすい。エディタ用の文法パッケージに入っている highlights.scm なども同じ形式で書かれており、書き方の参考になる。
✅ 次の記事では…
PART 05 では、ここまでの部品を組み合わせて、プロジェクト一式から型・メソッド・メソッド呼び出し・import を抽出し、JSONL とクラス間の依存グラフ(Mermaid)を出力する。