You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: website/advanced/faq.md
+12-10Lines changed: 12 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -2,10 +2,10 @@
2
2
3
3
## My pattern does not work, why?
4
4
5
-
1.**Use the Playground**: Test your pattern in the [ast-grep playground](https://ast-grep.github.io/playground.html).
5
+
1.**Use the Playground**: Test your pattern in the [ast-grep playground](/playground.html).
6
6
2.**Check for Valid Code**: Make sure your pattern is valid code that tree-sitter can parse.
7
7
3.**Ensure Correctness**: Use a [pattern object](/guide/rule-config/atomic-rule.html#pattern) to ensure your code is correct and unambiguous.
8
-
4.**Explore Examples**: See ast-grep's [catalog](https://ast-grep.github.io/catalog/) for more examples.
8
+
4.**Explore Examples**: See ast-grep's [catalog](/catalog/) for more examples.
9
9
10
10
11
11
The most common scenario is that you only want to match a sub-expression or one specific AST node in a whole syntax tree.
@@ -14,7 +14,7 @@ To make the code can be parsed by tree-sitter, you probably need more context in
14
14
15
15
For example, if you want to match key-value pair in JSON, writing `"key": "$VAL"` will not work because it is not a legal JSON.
16
16
17
-
Instead, you can provide context via the pattern object. See [playground code](https://ast-grep.github.io/playground.html#eyJtb2RlIjoiQ29uZmlnIiwibGFuZyI6Impzb24iLCJxdWVyeSI6ImZvbygkJCRBLCBiLCAkJCRDKSIsInJld3JpdGUiOiIiLCJjb25maWciOiJydWxlOlxuICBwYXR0ZXJuOiBcbiAgICBjb250ZXh0OiAne1widmVyc2lvblwiOiBcIiRWRVJcIiB9J1xuICAgIHNlbGVjdG9yOiBwYWlyIiwic291cmNlIjoie1xuICAgIFwidmVyc2lvblwiOiBcInZlclwiXG59In0=).
17
+
Instead, you can provide context via the pattern object. See [playground code](/playground.html#eyJtb2RlIjoiQ29uZmlnIiwibGFuZyI6Impzb24iLCJxdWVyeSI6ImZvbygkJCRBLCBiLCAkJCRDKSIsInJld3JpdGUiOiIiLCJjb25maWciOiJydWxlOlxuICBwYXR0ZXJuOiBcbiAgICBjb250ZXh0OiAne1widmVyc2lvblwiOiBcIiRWRVJcIiB9J1xuICAgIHNlbGVjdG9yOiBwYWlyIiwic291cmNlIjoie1xuICAgIFwidmVyc2lvblwiOiBcInZlclwiXG59In0=).
18
18
19
19
```YAML
20
20
rule:
@@ -25,7 +25,7 @@ rule:
25
25
26
26
The idea is that you can write full an valid code in the `context` field and use `selector` to select the sub-AST node.
27
27
28
-
This trick can be used in other languages as well, like [C](https://ast-grep.github.io/catalog/c/#match-function-call) and [Go](https://ast-grep.github.io/catalog/go/#match-function-call-in-golang).
28
+
This trick can be used in other languages as well, like [C](/catalog/c/#match-function-call) and [Go](/catalog/go/#match-function-call-in-golang). That said, pattern is not always the best choice for code search. [Rule](/guide/rule-config.html) can be more expressive and powerful.
29
29
30
30
## My Rule does not work, why?
31
31
Here are some tips to debug your rule:
@@ -36,22 +36,22 @@ Here are some tips to debug your rule:
36
36
37
37
## CLI and Playground produce different results, why?
38
38
39
-
The CLI and Playground may use different tree-sitter parsers. There are two main reasons why the results may differ:
39
+
There are two main reasons why the results may differ:
40
40
41
41
* **Parser Version**: The CLI may use a different version of the tree-sitter parser than the Playground.
42
42
Playground parsers are updated less frequently than the CLI, so there may be differences in the results.
43
-
* **Text Encoding**: The CLI and Playground may use different text encodings. CLI uses utf-8, while the Playground uses utf-16.
43
+
* **Text Encoding**: The CLI and Playground use different text encodings. CLI uses utf-8, while the Playground uses utf-16.
44
44
The encoding difference may cause different fallback parsing during [error recovery](https://github.com/tree-sitter/tree-sitter/issues/224).
45
45
46
-
To debug the issue, you can use the [`--debug-query`](/reference/cli/run.html#debug-query-format) flag in the CLI to see the parsed AST nodes and meta variables.
46
+
To debug the issue, you can use the [`--debug-query`](/reference/cli/run.html#debug-query-format) in the CLI to see the parsed AST nodes and meta variables.
47
47
48
48
```sh
49
49
sg run -p <PATTERN> --debug-query ast
50
50
```
51
51
52
52
The debug output will show the parsed AST nodes and you can compare them with the [Playground](/playground.html). You can also use different debug formats like `cst` or `pattern`.
53
53
54
-
If you find there are different results, it is usually caused by incomplete code snippet in the pattern. To fix the issue, you can provide a complete context code via the [pattern object](/reference/rule.html#atomic-rules).
54
+
Different results are usually caused by incomplete or wrong code snippet in the pattern. A common fix is to provide a complete context code via the [pattern object](/reference/rule.html#atomic-rules).
55
55
56
56
```yaml
57
57
rule:
@@ -60,7 +60,9 @@ rule:
60
60
selector: function
61
61
```
62
62
63
-
See [Pattern Deep Dive](/advanced/pattern-parse.html) for more context.
63
+
See [Pattern Deep Dive](/advanced/pattern-parse.html) for more context. Alternatively, you can try [rule](/guide/rule-config.html) instead.
64
+
65
+
Note `--debug-query` is not only for pattern, you can pass source code as `pattern` to see the parsed AST.
64
66
65
67
:::details Text encoding impacts tree-sitter error recovery.
66
68
Tree-sitter is a robust parser that can recover from syntax errors and continue parsing the rest of the code.
@@ -71,7 +73,7 @@ Text-encoding will affect the error recovery because it changed the cost of diff
71
73
:::
72
74
73
75
:::tip Found inconsistency?
74
-
If you find the inconsistency between CLI and Playground, please [open an issue in the Playground repository](https://github.com/ast-grep/ast-grep.github.io/issues).
76
+
If you find the inconsistency between CLI and Playground, please [open an issue in the Playground repository](https://github.com/ast-grep/ast-grep.github.io/issues). Contribution to update the Playground parser is warmly welcome!
0 commit comments