From 13648d70904628e0f795659407e921f752c41fbe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gustavo=20Gir=C3=A1ldez?= Date: Wed, 24 Jul 2024 11:34:23 -0400 Subject: [PATCH] Update documentation and changeset --- .changeset/gentle-shirts-deliver.md | 2 +- .../public/user-guide/tree-query-language.md | 18 ++++++++++-------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.changeset/gentle-shirts-deliver.md b/.changeset/gentle-shirts-deliver.md index c5eda1f6b..9175db2ea 100644 --- a/.changeset/gentle-shirts-deliver.md +++ b/.changeset/gentle-shirts-deliver.md @@ -2,4 +2,4 @@ "@nomicfoundation/slang": minor --- -Remove the ellipsis query operator making it implicit, and add an anchor operator +Remove the ellipsis query operator making it implicit, add an adjacency operator and make queries ignore trivia nodes. diff --git a/documentation/public/user-guide/tree-query-language.md b/documentation/public/user-guide/tree-query-language.md index 87a8bf815..d307b1ab4 100644 --- a/documentation/public/user-guide/tree-query-language.md +++ b/documentation/public/user-guide/tree-query-language.md @@ -44,6 +44,10 @@ is associated with each of the `StringExpression` children: --8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-5" ``` +Trivia nodes (whitespace, comments, etc.) will be skipped over when running a +query. Furthermore, trivia nodes cannot be explicitly (or implicitly with `_`) +matched by queries. + ### Capturing Nodes When matching patterns, you may want to process specific nodes within the @@ -108,10 +112,10 @@ This pattern would match a set of possible keyword terminals, capturing them as --8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:alternations-2" ``` -### Anchoring +### Adjacency -By using anchors `.`, you can constrain a pattern to only match the first or the -last child nodes. +By using the adjacency operator `.` you can constrain a pattern to only match +the first or the last child nodes. For example, the following pattern would match only the first parameter declaration in a function definition: @@ -126,12 +130,10 @@ And conversely the following will match only the last parameter: --8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:anchoring-2" ``` -If the anchor is used in between two patterns it constrains matches on both -patterns to occur consecutively, ie. without any other sibling node in between. -For example, this pattern matches pairs of consecutive statements: +If the adjacency operator is used in between two patterns it constrains matches +on both patterns to occur consecutively, ie. without any other sibling node in +between. For example, this pattern matches pairs of consecutive statements: ```{ .scheme } --8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:anchoring-3" ``` - -Anchors will skip over trivia nodes.