GritQL

GritQL 是一种用于对源代码执行结构化搜索的查询语言。这意味着在你的搜索查询中将忽略诸如空格或字符串中使用的引号类型之类的琐碎内容。此外，它还提供了许多功能，允许你查询语法结构，例如片段、匹配、嵌套和变量。

¥GritQL is a query language for performing structural searches on source code. This means that trivia such as whitespace or even the type of quotes used in strings will be ignored in your search query. In addition, it offers many features that allow you to query syntax structure such as snippets, matching, nesting, and variables.

GritQL 是 open-source 并由 Grit.io 创建。

¥GritQL is open-source and created by Grit.io.

Biome 使用 GritQL 有两个目的：

¥Biome uses GritQL for two purposes:

• 分析器插件。

  ¥The Analyzer Plugins.

• biome search 命令，我们希望将其扩展到我们的 IDE 扩展。

  ¥The biome search command, which we hope to extend to our IDE extensions as well.

模式

¥Patterns

GritQL 查询通过模式工作。你将看到的最常见的模式是代码片段，它看起来像用反引号封装的普通源代码：

¥GritQL queries work through patterns. The most common pattern you will see is the code snippet, which looks like ordinary source code wrapped in backticks:

`console.log('Hello, world!')`

此模式将匹配传递字符串 'Hello, world!' 的任何对 console.log() 的调用。但由于 GritQL 进行结构匹配，因此它不关心格式细节。这也匹配：

¥This pattern will match any call to console.log() that is passed the string 'Hello, world!'. But because GritQL does structural matching, it doesn’t care about formatting details. This also matches:

console.log (
    'Hello, world!'
)

这个也是如此（注意引号中的变化）：

¥And so does this (note the change in quotes):

console.log("Hello, world!")

Note

大多数 shell 将反引号解释为命令调用，这与 GritQL 的代码片段相冲突。因此，在使用 biome search 命令时，最好在 Grit 查询周围加上单引号：

¥Most shells interpret backticks as command invocations, which conflicts with GritQL’s code snippets. So when using the biome search command, it’s best to put single quotes around your Grit queries:

biome search '`console.log($message)`' # find all `console.log` invocations

变量

¥Variables

GritQL 查询也可以有变量。无论传递的消息是什么，以下内容都将匹配对 console.log() 的任何调用：

¥GritQL queries can also have variables. The following will match any call to console.log() regardless of the message passed:

`console.log($message)`

这也将匹配 console 对象上的任何方法：

¥This will match any of the methods on the console object too:

`console.$method($message)`

同一个变量名可以在一个代码片段中多次出现：

¥The same variable name can occur multiple times in a single snippet:

`$fn && $fn()`

这将匹配 foo && foo()，甚至 foo.bar && foo.bar()，但不匹配 foo && bar()。

¥This will match foo && foo(), and even foo.bar && foo.bar(), but not foo && bar().

条件

¥Conditions

你可以使用 where 运算符向模式添加条件。这通常与匹配运算符 <: 一起使用：

¥You can add conditions to patterns by using the where operator. This is commonly used together with the match operator, <::

`console.$method($message)` where {
    $method <: `log`
}

此查询与我们之前看到的 console.log($message) 模式相同，但在组合中添加其他运算符时，它会变得更有趣：

¥This query is identical to the console.log($message) pattern we saw earlier, but it gets quickly more interesting when add other operators in the mix:

`console.$method($message)` where {
    $method <: or { `log`, `info`, `warn`, `error` }
}

匹配 Biome 语法节点

¥Matching Biome Syntax Nodes

要进行更精确的查询，你可以直接匹配 Biome 的内部语法节点。每个节点都由一个唯一的 PascalCase 名称标识。

¥For more precise queries, you can match against Biome’s internal syntax nodes directly. Each node is identified by a unique PascalCase name.

例如，要查找所有 JavaScript if 语句，你可以匹配 JsIfStatement 节点：

¥For example, to find all JavaScript if statements, you can match the JsIfStatement node:

engine biome(1.0)
language js(typescript,jsx)

JsIfStatement() as $stmt where {
  register_diagnostic(
    span=$stmt,
    message="Found an if statement"
  )
}

你可以通过浏览 Biome Playground 中的语法树来发现代码的节点名称。所有可用节点的完整列表也位于 Biome 仓库 xtask/codegen 目录下的 .ungram 文件中。

¥You can discover node names for your code by exploring the syntax tree in the Biome Playground. A complete list of all available nodes is also available in the .ungram files in the xtask/codegen directory of the Biome repository.

Caution

Biome 的语法在不同版本之间可能会有所变化，尤其是在新语言方面。这可能会导致节点名称更改，从而破坏你的模式。升级 Biome 时，请准备好更新你的查询。

¥Biome’s grammar can change between versions, especially for new languages. This may cause node names to change, which could break your patterns. Be prepared to update your queries when upgrading Biome.

语言文档

¥Language Documentation

有关 GritQL 及其语法的更多信息，请参阅官方 GritQL 语言文档。

¥For more information about GritQL and its syntax, see the official GritQL Language Documentation.

请记住，Biome 尚不支持 Grit 的所有功能。

¥Please keep in mind that Biome doesn’t support all of Grit’s features (yet).

集成状态

¥Integration Status

Biome 中的 GritQL 支持正在积极开发中。许多东西已经可以工作了，但仍有错误在所难免，而且有些功能仍然完全缺失。

¥GritQL support in Biome is actively being worked on. Many things already work, but bugs are still expected and some features are still outright missing.

有关支持哪些 GritQL 功能以及哪些功能仍在进行中的详细概述，请参阅 GitHub 问题：https://github.com/biomejs/biome/issues/2582。

¥For a detailed overview of which GritQL features are supported and which are still in-progress, please see the GitHub issue: https://github.com/biomejs/biome/issues/2582.

我们还有一个详细的 RFC，它指导我们插件工作的方向：https://github.com/biomejs/biome/discussions/1762

¥We also have a detailed RFC which guides the direction for our plugin efforts: https://github.com/biomejs/biome/discussions/1762

tl;dr:我们正在支持插件，可以是纯 GritQL 插件，也可以是使用 GritQL 选择他们希望操作的代码的 JS/TS 插件。敬请期待！

¥tl;dr: We are working on supporting plugins, which can be either pure GritQL plugins or JS/TS plugins that use GritQL to select the code they wish to operate on. Stay tuned!