Back to Details

ast-grep

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ast-grep

ast-grep

Workflow

工作流

  1. Write a test snippet representing the target code
  2. Write the rule (start with 
    pattern
    , escalate to 
    kind
    + 
    has
    /
    inside
    if needed)
  3. Test with 
    --stdin
    before searching the codebase
  4. Search the codebase once the rule matches
  1. 编写代表目标代码的测试片段
  2. 编写规则（从 
    pattern
    开始，必要时升级为 
    kind
    + 
    has
    /
    inside
    组合）
  3. 在搜索整个代码库前，先用 
    --stdin
    测试
  4. 规则匹配成功后，再对代码库进行全量搜索

Critical Gotchas

关键注意事项

Always use 
stopBy: end
on relational rules

关系型规则务必使用 
stopBy: end

Without it, 
has
/
inside
stop at the first non-matching node instead of traversing the full subtree:
yaml
undefined
若缺少该配置，
has
/
inside
会在第一个不匹配的节点处停止，而不会遍历完整的子树：
yaml
undefined

WRONG — will miss deeply nested matches

WRONG — will miss deeply nested matches

has: pattern: await $EXPR
has: pattern: await $EXPR

RIGHT

RIGHT

has: pattern: await $EXPR stopBy: end
undefined
has: pattern: await $EXPR stopBy: end
undefined

Escape metavariables in shell

在 Shell 中转义元变量

$VAR
gets interpreted by the shell. Either escape or single-quote:
bash
undefined
$VAR
会被 Shell 解析，需要转义或使用单引号包裹：
bash
undefined

Double-quoted: escape with backslash

Double-quoted: escape with backslash

ast-grep scan --inline-rules "id: test language: javascript rule: pattern: await $EXPR" .
ast-grep scan --inline-rules "id: test language: javascript rule: pattern: await $EXPR" .

Single-quoted: no escaping needed

Single-quoted: no escaping needed

ast-grep scan --inline-rules 'id: test language: javascript rule: pattern: await $EXPR' .
undefined
ast-grep scan --inline-rules 'id: test language: javascript rule: pattern: await $EXPR' .
undefined

Metavariables must be the sole content of an AST node

元变量必须是 AST 节点的唯一内容

These don't work: 
obj.on$EVENT
, 
"Hello $WORLD"
, 
a $OP b
, 
$jq
Use 
$$OP
for unnamed nodes (operators, punctuation). Use 
$$$ARGS
for zero-or-more nodes.
以下写法无效：
obj.on$EVENT
、
"Hello $WORLD"
、
a $OP b
、
$jq
对于未命名节点（运算符、标点符号），请使用 
$$OP
；对于零个或多个节点，请使用 
$$$ARGS
。

Testing with --stdin

使用 --stdin 进行测试

bash
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules 'id: test
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end' --stdin
bash
echo "async function test() { await fetch(); }" | ast-grep scan --inline-rules 'id: test
language: javascript
rule:
  kind: function_declaration
  has:
    pattern: await $EXPR
    stopBy: end' --stdin

Debugging with --debug-query

使用 --debug-query 调试

When rules don't match, inspect the AST to find correct 
kind
values:
bash
ast-grep run --pattern 'your code here' --lang javascript --debug-query=cst
Formats: 
cst
(all nodes), 
ast
(named only), 
pattern
(how ast-grep sees your pattern).
当规则无法匹配时，检查 AST 以找到正确的 
kind
值：
bash
ast-grep run --pattern 'your code here' --lang javascript --debug-query=cst
格式选项：
cst
（所有节点）、
ast
（仅命名节点）、
pattern
（ast-grep 解析后的模式结构）。

Rule syntax

规则语法

See 
references/rule_reference.md
for the full rule reference (atomic, relational, composite rules, and metavariables).
完整的规则参考（原子规则、关系规则、复合规则及元变量）请查看 
references/rule_reference.md
。