Skip to content

Commit b265d0c

Browse files
fix: add docs
1 parent f31df5a commit b265d0c

File tree

3 files changed

+10
-3
lines changed

3 files changed

+10
-3
lines changed

website/advanced/faq.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ If your rule depends on using meta variables in later rules, the best way is to
178178

179179
The most common scneario is that your pattern is parsed as a different AST node than you expected. And you may use `kind` rule to filter out the AST node you want to match. This does not work in ast-grep for two reasons:
180180
1. tree-sitter, the underlying parser library, does not offer a way to parse a string of a specific kind. So `kind` rule cannot be used to change the parsing outcome of a `pattern`.
181-
2. ast-grep rules are independent of each other. `pattern` will behave the same regardless of another `kind` rule.
181+
2. ast-grep rules are mostly independent of each other, except sharing meta-variables during a match. `pattern` will behave the same regardless of another `kind` rule.
182182

183183
To specify the `kind` of a `pattern`, you need to use [pattern](http://localhost:5173/guide/rule-config/atomic-rule.html#pattern-object) [object](/advanced/pattern-parse.html#incomplete-pattern-code).
184184

@@ -190,7 +190,7 @@ pattern: a = 123 # rule 1
190190
kind: field_definition # rule 2
191191
```
192192

193-
This is because pattern `a = 123` is parsed as [`assignment_expression`](/playground.html#eyJtb2RlIjoiUGF0Y2giLCJsYW5nIjoiamF2YXNjcmlwdCIsInF1ZXJ5IjoiYSA9IDEyMyIsInJld3JpdGUiOiIiLCJzdHJpY3RuZXNzIjoic21hcnQiLCJzZWxlY3RvciI6IiIsImNvbmZpZyI6IiIsInNvdXJjZSI6IiJ9). Pattern and kind are two independent rules. And using them together will match nothing because no AST will have both `assignment_expression` and `field_definition` kind at once.
193+
This is because pattern `a = 123` is parsed as [`assignment_expression`](/playground.html#eyJtb2RlIjoiUGF0Y2giLCJsYW5nIjoiamF2YXNjcmlwdCIsInF1ZXJ5IjoiYSA9IDEyMyIsInJld3JpdGUiOiIiLCJzdHJpY3RuZXNzIjoic21hcnQiLCJzZWxlY3RvciI6IiIsImNvbmZpZyI6IiIsInNvdXJjZSI6IiJ9). Pattern and kind are two separate rules. And using them together will match nothing because no AST will have both `assignment_expression` and `field_definition` kind at once.
194194

195195
Instead, you need to use pattern object to provide enough context code for the parser to parse the code snippet as `field_definition`:
196196

website/guide/rule-config/atomic-rule.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,13 @@ Here are some situations that you can effectively use `kind`:
118118
3. Patterns only appear within specific context, e.g. the class property definition.
119119

120120

121+
:::warning `kind` + `pattern` is different from pattern object
122+
You may want to use `kind` to change how `pattern` is parsed. However, ast-grep rules are independent of each other.
123+
124+
To change the parsing behavior of `pattern`, you should use pattern object with `context` and `selector` field.
125+
See [this FAQ](/advanced/faq.html#kind-and-pattern-rules-are-not-working-together-why).
126+
:::
127+
121128
## `regex`
122129

123130
The `regex` atomic rule will match the AST node by its text against a Rust regular expression.

website/guide/rule-config/composite-rule.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -164,4 +164,4 @@ It has less indentation than before. See the rewritten rule [in action](/playgro
164164
Rule object does not guarantee the order of rule matching. It is possible that the `inside` rule matches before the `pattern` rule in the example above.
165165
:::
166166

167-
Rule order is not important if rules are independent. However, matching metavaraible in patterns depends on the result of previous pattern matching. If you use pattern with [meta variables](/guide/pattern-syntax.html#meta-variable-capturing), make sure to use `all` array to guarantee rule execution order.
167+
Rule order is not important if rules are completely independent. However, matching metavaraible in patterns depends on the result of previous pattern matching. If you use pattern with [meta variables](/guide/pattern-syntax.html#meta-variable-capturing), make sure to use `all` array to guarantee rule execution order.

0 commit comments

Comments
 (0)