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'

或通过带有-Q/--query-file参数的查询文件路径（通常是*.scm）

$ 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 “内建”了对以下语言的搜索支持

• C
• C++
• C#
• CSS
• Dockerfile
• Elisp
• Elm
• Go
• HTML
• Java
• JavaScript
• JSON
• Kotlin
• Lua
• Objective-C
• Python
• Ruby
• Rust
• Swift
• Toml
• tree-sitter 查询（多么元！)
• TypeScript

理论上，任何发布了/可用的树-sitter 语法crate的语言都应该是“公平游戏”。将来，我们可能会支持动态指定/加载其他语言

或者，请随意提交问题，请求“内建”对其他语言的支持

将查询限制为特定文件/语言

默认情况下，tree-sitter-grep会递归搜索所有“非忽略/隐藏”的文件，包括支持的编程语言/类型。如果它可以对该语言的语法进行解析，则会搜索该文件的文本内容以查找匹配项。

要显式指定/限制为单个语言，请使用-l/--language参数。

$ 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

总的来说，我们希望与ripgrep兼容

性能

我没有进行过任何“真正的”基准测试，但普遍的看法似乎是tree-sitter-grep运行得相当快，令人惊讶（考虑到tree-sitter并没有针对“从头开始解析”的使用场景进行优化）

对于“不是很大的”代码库，我倾向于看到它在< 100ms内运行

对于“巨大的”代码库，例如扫描> 300k行代码和输出> 7000个匹配项，我看到它运行在大约360ms，这仍然感觉“相当快”

编辑器集成

TODO，我相信@peterstuart已经编写了一个Emacs插件的初始版本，而我开始尝试编写一个neovim插件

基本思路可能是，您将能够以与eg grep/ripgrep匹配项交互的方式与tree-sitter-grep的匹配项交互

欢迎贡献/如果您为您的首选编辑器编写了插件，请告诉我们

非目标

• 试图支持“一切”功能（是的，这有点像ast-grep的阴影）

  我们认为tree-sitter-grep本身肯定有潜力成为一个有用的grep-like工具，并且除此之外，我们将其视为一个“构建块”，理论上可以被其他工具利用，例如用于搜索和替换、代码修改等

  我已经在使用tree-sitter-grep作为“一次性大规模自动化重构”的一部分取得了成功

• 正在考虑创建我们自己的自定义查询语法（哎呀，这里的阴影真多）

  我实际上认为eg ast-grep采取的方法，即提供一种“看起来像代码”的查询语法，是非常直观的，也许在许多情况下是最容易触及的

  但我个人并不倾向于将这种方法作为工具的途径。我不喜欢它隐藏了“tree-sitter的所有内容”。它感觉像tree-sitter在一般上非常适合在底层技术上构建各种类型的工具，所以我更倾向于“构建块”，这可以让您利用现有的知识/专业知识，并且本质上引导您走向获得更多这种知识/专业知识的道路。也许然后在此基础上（或受其启发）构建您自己的东西

贡献/问题

代码库是一个相当典型的基于cargo的Rust项目

例如，cargo test运行测试套件

请随时打开问题或提出拉取请求