tree-sitter-grep

tree-sitter-grep 是一个类似grep的搜索工具，它递归地搜索当前目录中的 tree-sitter查询 模式。

双许可下MIT或UNLICENSE。

• 安装
• 使用方法
• 性能
• 编辑器集成
• 非目标
• 贡献/问题

安装

安装了 Rust工具链 后，运行

$ cargo install tree-sitter-grep

使用方法

$ tree-sitter-grep -q '(trait_bounds) @t'
src/core.rs:14:pub struct Core<'s, M: 's, S> {
src/core.rs:30:impl<'s, M: Matcher, S: Sink> Core<'s, M, S> {
src/mod.rs:622:        P: AsRef<Path>,
src/mod.rs:623:        M: Matcher,
src/mod.rs:624:        S: Sink,
src/mod.rs:644:        M: Matcher,
[...]

指定查询

tree-sitter-grep 使用 tree-sitter查询 来指定“模式”进行匹配

你可以通过 -q/--query 参数“内联”指定查询

$ tree-sitter-grep -q '(trait_bounds) @t'

或者通过指定到tree-sitter查询文件的路径（通常为 *.scm）使用 -Q/--query-file 参数

$ cat queries/trait_bounds.scm
(trait_bounds) @t
$ tree-sitter-grep -Q queries/trait_bounds.scm

tree-sitter-grep 使用tree-sitter查询“捕获”(@ whatever)来指定“匹配”的tree-sitter AST节点

所以你的查询必须始终包含至少一个捕获

如果你的查询包含多个捕获（例如，如果你正在使用“预组合”查询或使用 谓词），tree-sitter-grep默认将查询中的第一个捕获（按字典顺序，我认为？）用作其“目标捕获”

要覆盖该行为，你可以传递 -c/--capture 参数

$ tree-sitter-grep -q '((field_declaration name: (field_identifier) @field_name (#eq? @field_name "pos")) @f)' --capture f

我如何确定我想要的查询是什么？

作为起点，阅读 tree-sitter查询文档 是值得的

为了确定你想要编写的查询的相关树-sitter AST结构，一个树-sitter "游乐场"非常有价值，例如交互式在线版，或者我使用neovim的:InspectTree

在我的经验中，尽管树-sitter查询是一个稳固的起点，但它们并不总是足够“表达性”，以至于能够精确指定你想要匹配的AST节点集合

因此，我们还支持指定过滤器插件，你可以在其中对匹配或不匹配的条件有“完全的程序控制”

支持的查询“谓词”

树-sitter查询谓词允许执行一些匹配树-sitter AST节点的“过滤”操作

我们使用Rust tree-sitter绑定，因此“我们支持它们所做的任何谓词”

具体包括

• #eq?

$ tree-sitter-grep -q '((field_declaration name: (field_identifier) @field_name (#eq? @field_name "pos")) @f)' --capture f
src/core.rs:20:    pos: usize,

• #match?

$ tree-sitter-grep -q '((field_declaration name: (field_identifier) @field_name (#match? @field_name "^p")) @f)' --capture f
src/core.rs:20:    pos: usize,
src/mod.rs:157:    passthru: bool,

过滤器插件

当你需要“编程语言的力量”来完全指定匹配“标准”时，你可以编写一个“过滤器插件”

使用过滤器插件

如果你有一个现有的过滤器插件，你可以通过-f/--filter参数（带编译好的过滤器动态库文件的路径.so/.dll/.dylib文件）来指定你想使用它

$ tree-sitter-grep -q '(trait_bounds) @t' -f path/to/libmy-filter.so

如果过滤器插件期望传递一个“过滤器参数”（例如，用于以某种方式参数化/配置其行为），则可以使用-a/--filter-arg参数来指定

$ tree-sitter-grep -q '(trait_bounds) @t' -f path/to/libmy-filter-that-expects-argument.so -a '{ the_filter_plugin_can_parse_this: "however_it_wants" }'

值得注意的是，从技术上讲，如果你提供过滤器插件参数，你甚至不需要传递树-sitter查询参数（在这种情况下，过滤器插件将对“每个”树-sitter AST节点进行调用）

编写过滤器插件

TODO：添加一个“指南”

简而言之

虽然在理论上你可以在其他语言中编写过滤器插件，但“最佳路径”是在Rust中编写，并使用examples/中的示例过滤器插件作为起点/参考

基本思路是，对于每个根据提供的查询参数可能匹配的树-sitter AST节点，过滤器插件随后还会被调用，并指示它是否认为该节点是匹配的（基本上作为一个(&tree_sitter::Node) -> bool "谓词"）

$ tree-sitter-grep -q '(trait_bounds) @t' -l rust

$ tree-sitter-grep -q '(trait_bounds) @t' src/main.rs src/compiler

$ tree-sitter-grep --help