From 5eed3830c08fd1b833f1a28e8f9b66f831216952 Mon Sep 17 00:00:00 2001 From: Igor Matuszewski Date: Thu, 11 Apr 2024 10:26:58 +0100 Subject: [PATCH] Standardize on tree-query-language --- .../cargo/tests/src/doc_examples/mod.rs | 2 +- ...ery_language.rs => tree_query_language.rs} | 0 documentation/public/user-guide/NAV.md | 2 +- documentation/public/user-guide/concepts.md | 2 +- .../user-guide/npm-package/using-queries.md | 2 +- .../user-guide/rust-crate/using-queries.md | 2 +- ...ery-language.md => tree-query-language.md} | 24 +++++++++---------- 7 files changed, 17 insertions(+), 17 deletions(-) rename crates/solidity/outputs/cargo/tests/src/doc_examples/{query_language.rs => tree_query_language.rs} (100%) rename documentation/public/user-guide/{query-language.md => tree-query-language.md} (73%) diff --git a/crates/solidity/outputs/cargo/tests/src/doc_examples/mod.rs b/crates/solidity/outputs/cargo/tests/src/doc_examples/mod.rs index ce68d8dfce..05756c0833 100644 --- a/crates/solidity/outputs/cargo/tests/src/doc_examples/mod.rs +++ b/crates/solidity/outputs/cargo/tests/src/doc_examples/mod.rs @@ -1,4 +1,4 @@ -mod query_language; +mod tree_query_language; mod using_queries; mod using_the_cursor; mod using_the_parser; diff --git a/crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs b/crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs similarity index 100% rename from crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs rename to crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs diff --git a/documentation/public/user-guide/NAV.md b/documentation/public/user-guide/NAV.md index 39a6177446..b3ce2bab8d 100644 --- a/documentation/public/user-guide/NAV.md +++ b/documentation/public/user-guide/NAV.md @@ -1,5 +1,5 @@ - [Introduction](./introduction.md) - [Concepts](./concepts.md) -- [Tree Query Language](./query-language.md) +- [Tree Query Language](./tree-query-language.md) - [Rust Crate](./rust-crate/) - [NPM Package](./npm-package/) diff --git a/documentation/public/user-guide/concepts.md b/documentation/public/user-guide/concepts.md index 44c6976ff0..d4762dbcf9 100644 --- a/documentation/public/user-guide/concepts.md +++ b/documentation/public/user-guide/concepts.md @@ -59,7 +59,7 @@ allows you to reuse the same query in multiple places. Queries can largely replace the need for both internal (cursor), and external (visitor) iterator patterns. -The [query language](./query-language.md) is based on pattern matching, and the +The [query language](./tree-query-language.md) is based on pattern matching, and the execution semantics are closer to unification than to regular expression matching i.e. a query returns all possible matches, not just the longest/shortest/first/last match. There is no concept of a 'greedy' operator diff --git a/documentation/public/user-guide/npm-package/using-queries.md b/documentation/public/user-guide/npm-package/using-queries.md index b1c2b1e8db..89c25d408b 100644 --- a/documentation/public/user-guide/npm-package/using-queries.md +++ b/documentation/public/user-guide/npm-package/using-queries.md @@ -2,7 +2,7 @@ It's often more convenient to use the declarative `Query` API to traverse the CST, as they allow you to express your intent more concisely and can largely replace the need for both internal (cursor), and external (visitor) iterator patterns. -The [query language](./../query-language.md) is based on pattern matching, and the execution semantics are closer to unification than to regular expression matching. A query returns all possible matches, not just the longest/shortest/first/last match. +The [query language](./../tree-query-language.md) is based on pattern matching, and the execution semantics are closer to unification than to regular expression matching. A query returns all possible matches, not just the longest/shortest/first/last match. If not specified otherwise, let's assume we already parsed a Solidity source and have a `cursor` pointing to the root node of the CST (created with `createTreeCursor`, see [Using the Cursor](./using-the-cursor.md)). diff --git a/documentation/public/user-guide/rust-crate/using-queries.md b/documentation/public/user-guide/rust-crate/using-queries.md index 50e3f84f72..16b253d276 100644 --- a/documentation/public/user-guide/rust-crate/using-queries.md +++ b/documentation/public/user-guide/rust-crate/using-queries.md @@ -2,7 +2,7 @@ It's often more convenient to use the declarative `Query` API to traverse the CST, as they allow you to express your intent more concisely and can largely replace the need for both internal (cursor), and external (visitor) iterator patterns. -The [query language](./../query-language.md) is based on pattern matching, and the execution semantics are closer to unification than to regular expression matching. A query returns all possible matches, not just the longest/shortest/first/last match. +The [query language](./../tree-query-language.md) is based on pattern matching, and the execution semantics are closer to unification than to regular expression matching. A query returns all possible matches, not just the longest/shortest/first/last match. If not specified otherwise, let's assume we already parsed a Solidity source and have a `cursor` pointing to the root node of the CST (created with `create_tree_cursor`, see [Using the Cursor](./using-the-cursor.md)). diff --git a/documentation/public/user-guide/query-language.md b/documentation/public/user-guide/tree-query-language.md similarity index 73% rename from documentation/public/user-guide/query-language.md rename to documentation/public/user-guide/tree-query-language.md index 59879c9ef8..b8d03843a7 100644 --- a/documentation/public/user-guide/query-language.md +++ b/documentation/public/user-guide/tree-query-language.md @@ -10,7 +10,7 @@ example, this pattern would match any `MultiplicativeExpression` node whose chil are exactly two `Expression` nodes, with an `Asterisk` node in between (no whitespace): ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:query-syntax-1" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-1" ``` The children of a node can optionally be named. The name is a property of the edge from @@ -18,14 +18,14 @@ the node to the child, and is not a property of the child. For example, this pat a `MultiplicativeExpression` node with the two `Expression` children named `left_operand` and `right_operand`: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:query-syntax-2" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-2" ``` You can also match a node's textual content using a string literal. For example, this pattern would match a `MultiplicativeExpression` with a `*` operator (for clarity): ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:query-syntax-3" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-3" ``` If you don't care about the kind of a node, you can use an underscore `_`, which matches any kind. @@ -33,7 +33,7 @@ For example, this pattern will match a `MultiplicativeExpression` node with two children, one of any kind named `left_operand` and one of any kind: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:query-syntax-4" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-4" ``` Children can also be elided. For example, this would produce multiple matches for a @@ -41,7 +41,7 @@ Children can also be elided. For example, this would produce multiple matches fo is associated with each of the `StringExpression` children: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:query-syntax-5" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:query-syntax-5" ``` ### Capturing Nodes @@ -55,14 +55,14 @@ For example, this pattern would match any struct definition and it would associa the name `struct_name` with the identifier: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:capturing-nodes-1" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:capturing-nodes-1" ``` And this pattern would match all event definitions for a contract, associating the name `event_name` with the event name, `contract_name` with the containing contract name: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:capturing-nodes-2" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:capturing-nodes-2" ``` ### Quantification @@ -75,20 +75,20 @@ matches _one or more_. For example, this pattern would match a sequence of one or more comments at the top of the file: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:quantification-1" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:quantification-1" ``` This pattern would match a contract definition with at least one doc comment, capturing them: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:quantification-2" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:quantification-2" ``` This pattern would match all function calls, capturing a string argument if one was present: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:quantification-3" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:quantification-3" ``` ### Alternations @@ -99,11 +99,11 @@ For example, this pattern would match a call to either a variable or an object p In the case of a variable, capture it as `@function`, and in the case of a property, capture it as `@method`: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:alternations-1" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:alternations-1" ``` This pattern would match a set of possible keyword tokens, capturing them as `@keyword`: ```{ .scheme } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/query_language.rs:alternations-2" +--8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/tree_query_language.rs:alternations-2" ```