diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ccbf0af84e..03d88d4031 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -74,13 +74,15 @@ jobs: env: | NPM_TOKEN=${{ secrets.NPM_TOKEN }} - - name: "infra publish cargo" - if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}" - uses: "./.github/actions/devcontainer/run" - with: - runCmd: "./scripts/bin/infra publish cargo" - env: | - CARGO_REGISTRY_TOKEN=${{ secrets.CARGO_REGISTRY_TOKEN }} + # __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) + # + # - name: "infra publish cargo" + # if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}" + # uses: "./.github/actions/devcontainer/run" + # with: + # runCmd: "./scripts/bin/infra publish cargo" + # env: | + # CARGO_REGISTRY_TOKEN=${{ secrets.CARGO_REGISTRY_TOKEN }} - name: "infra publish github-release" if: "${{ steps.runChangesets.outputs.hasChangesets == 'false' }}" diff --git a/README.md b/README.md index 02becfa070..bfdc505e6a 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,12 @@ [![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/slang_solidity?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/slang_solidity) [![npm](https://img.shields.io/npm/v/@nomicfoundation/slang?label=NPM%20Package&logo=npm&logoColor=white)](https://www.npmjs.com/package/@nomicfoundation/slang) -[![documentation](https://img.shields.io/github/deployments/NomicFoundation/slang/github-pages?label=Documentation&logo=gitbook&logoColor=white)](https://nomicfoundation.github.io/slang) + + ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) @@ -14,13 +17,17 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [Slang Internals](https://nomicfoundation.github.io/slang/latest/internals/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) This repository maintains the source code and release process for these projects: -- [Slang Rust Crate + CLI](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) -- [Slang TypeScript Package](https://nomicfoundation.github.io/slang/latest/user-guide/npm-package/) - [Solidity Language Specification](https://nomicfoundation.github.io/slang/latest/solidity-specification/) +- [Slang NPM Package](https://www.npmjs.com/package/@nomicfoundation/slang/) + + > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/infra/cli/src/commands/publish/cargo/mod.rs b/crates/infra/cli/src/commands/publish/cargo/mod.rs index 189296eebb..e1d3ddfdb3 100644 --- a/crates/infra/cli/src/commands/publish/cargo/mod.rs +++ b/crates/infra/cli/src/commands/publish/cargo/mod.rs @@ -1,7 +1,7 @@ use std::iter::once; use std::path::Path; -use anyhow::Result; +use anyhow::{ensure, Result}; use clap::Parser; use infra_utils::cargo::{CargoWorkspace, UserFacingCrate}; use infra_utils::commands::Command; @@ -20,6 +20,11 @@ pub struct CargoController { impl CargoController { pub fn execute(&self) -> Result<()> { + ensure!( + false, + "__SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync)" + ); + let mut changeset = TemporaryChangeset::new( "infra/cargo-publish", "prepare Cargo packages for publishing", diff --git a/crates/metaslang/bindings/Cargo.toml b/crates/metaslang/bindings/Cargo.toml index e70a944678..2def5b1390 100644 --- a/crates/metaslang/bindings/Cargo.toml +++ b/crates/metaslang/bindings/Cargo.toml @@ -2,7 +2,8 @@ version.workspace = true rust-version.workspace = true edition.workspace = true -publish = true +# __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) +# publish = true name = "metaslang_bindings" description = "Computes semantic language bindings from parsed source code" diff --git a/crates/metaslang/bindings/README.md b/crates/metaslang/bindings/README.md index c290b0065f..f54c5b4c3d 100644 --- a/crates/metaslang/bindings/README.md +++ b/crates/metaslang/bindings/README.md @@ -2,9 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/metaslang_bindings?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/metaslang_bindings) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -12,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/metaslang/cst/Cargo.toml b/crates/metaslang/cst/Cargo.toml index 9adecf73ed..be86cca818 100644 --- a/crates/metaslang/cst/Cargo.toml +++ b/crates/metaslang/cst/Cargo.toml @@ -2,7 +2,8 @@ version.workspace = true rust-version.workspace = true edition.workspace = true -publish = true +# __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) +# publish = true name = "metaslang_cst" description = "A generic library for building, navigating and querying concrete syntax trees." diff --git a/crates/metaslang/cst/README.md b/crates/metaslang/cst/README.md index 700a274f42..ea33a49bfd 100644 --- a/crates/metaslang/cst/README.md +++ b/crates/metaslang/cst/README.md @@ -2,9 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/metaslang_cst?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/metaslang_cst) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -12,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/metaslang/graph_builder/Cargo.toml b/crates/metaslang/graph_builder/Cargo.toml index 0626da23a6..c1d47a2f39 100644 --- a/crates/metaslang/graph_builder/Cargo.toml +++ b/crates/metaslang/graph_builder/Cargo.toml @@ -2,7 +2,8 @@ version.workspace = true rust-version.workspace = true edition.workspace = true -publish = true +# __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) +# publish = true name = "metaslang_graph_builder" description = "Construct graphs from parsed source code" diff --git a/crates/metaslang/graph_builder/README.md b/crates/metaslang/graph_builder/README.md index ab243861b1..b02df04b6f 100644 --- a/crates/metaslang/graph_builder/README.md +++ b/crates/metaslang/graph_builder/README.md @@ -2,9 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/metaslang_graph_builder?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/metaslang_graph_builder) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -12,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/solidity/outputs/cargo/cli/Cargo.toml b/crates/solidity/outputs/cargo/cli/Cargo.toml index b3249b251b..2e94f8d4d5 100644 --- a/crates/solidity/outputs/cargo/cli/Cargo.toml +++ b/crates/solidity/outputs/cargo/cli/Cargo.toml @@ -2,7 +2,8 @@ version.workspace = true rust-version.workspace = true edition.workspace = true -publish = true +# __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) +# publish = true name = "slang_solidity_cli" description = "This crate contains the 'slang_solidity' CLI/cargo binary. Please see the 'slang_solidity' crate for more information." diff --git a/crates/solidity/outputs/cargo/cli/README.md b/crates/solidity/outputs/cargo/cli/README.md index 36b4fe6a90..2b57193d26 100644 --- a/crates/solidity/outputs/cargo/cli/README.md +++ b/crates/solidity/outputs/cargo/cli/README.md @@ -2,9 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/slang_solidity_cli?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/slang_solidity_cli) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -12,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/solidity/outputs/cargo/crate/Cargo.toml b/crates/solidity/outputs/cargo/crate/Cargo.toml index 9aa011fa5b..3519125a2c 100644 --- a/crates/solidity/outputs/cargo/crate/Cargo.toml +++ b/crates/solidity/outputs/cargo/crate/Cargo.toml @@ -2,7 +2,8 @@ version.workspace = true rust-version.workspace = true edition.workspace = true -publish = true +# __SLANG_CARGO_PUBLISH_TEMPORARILY_DISABLED__ (keep in sync) +# publish = true name = "slang_solidity" description = "A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. Written in Rust and distributed in multiple languages." diff --git a/crates/solidity/outputs/cargo/crate/README.md b/crates/solidity/outputs/cargo/crate/README.md index 4f133f53d1..6641f3cb62 100644 --- a/crates/solidity/outputs/cargo/crate/README.md +++ b/crates/solidity/outputs/cargo/crate/README.md @@ -2,11 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/slang_solidity?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/slang_solidity) -[![npm](https://img.shields.io/npm/v/@nomicfoundation/slang?label=NPM%20Package&logo=npm&logoColor=white)](https://www.npmjs.com/package/@nomicfoundation/slang) -[![documentation](https://img.shields.io/github/deployments/NomicFoundation/slang/github-pages?label=Documentation&logo=gitbook&logoColor=white)](https://nomicfoundation.github.io/slang) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -14,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/rust-crate/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/crates/solidity/outputs/npm/package/README.md b/crates/solidity/outputs/npm/package/README.md index bf40d90687..ddca92fb49 100644 --- a/crates/solidity/outputs/npm/package/README.md +++ b/crates/solidity/outputs/npm/package/README.md @@ -2,11 +2,6 @@ -[![release](https://img.shields.io/github/v/tag/NomicFoundation/slang?label=GitHub%20Release&logo=github&sort=semver&logoColor=white)](https://github.com/NomicFoundation/slang/releases) -[![crate](https://img.shields.io/crates/v/slang_solidity?label=Rust%20Crate&logo=rust&logoColor=white)](https://crates.io/crates/slang_solidity) -[![npm](https://img.shields.io/npm/v/@nomicfoundation/slang?label=NPM%20Package&logo=npm&logoColor=white)](https://www.npmjs.com/package/@nomicfoundation/slang) -[![documentation](https://img.shields.io/github/deployments/NomicFoundation/slang/github-pages?label=Documentation&logo=gitbook&logoColor=white)](https://nomicfoundation.github.io/slang) - ## Solidity compiler tooling by [@NomicFoundation](https://github.com/NomicFoundation) A modular set of compiler APIs empowering the next generation of Solidity code analysis and developer tooling. @@ -14,7 +9,7 @@ Written in Rust and distributed in multiple languages. - [Announcement Post](https://medium.com/nomic-foundation-blog/slang-rethnet-2ad465fd7880) - [How to write your own Solidity linter using Slang, in 25 lines of code!](https://blog.nomic.foundation/how-to-write-your-own-solidity-linter-using-slang-356e7565ad1b/) -- [User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/npm-package/) +- [Slang User Guide](https://nomicfoundation.github.io/slang/latest/user-guide/) > ❗ This project is still in alpha, and is under active development. > If you are planning on using it, please [reach out to us on Telegram](https://t.me/+pxApdT-Ssn5hMTFh) so we can help you get started. diff --git a/documentation/public/user-guide/.navigation.md b/documentation/public/user-guide/.navigation.md index 14660d0282..1ba4fd4da8 100644 --- a/documentation/public/user-guide/.navigation.md +++ b/documentation/public/user-guide/.navigation.md @@ -2,5 +2,4 @@ - [Introduction](./introduction.md) - [Concepts](./concepts.md) - [Tree Query Language](./tree-query-language.md) -- [Rust Crate](./rust-crate/) - [NPM Package](./npm-package/) diff --git a/documentation/public/user-guide/index.md b/documentation/public/user-guide/index.md index c9d05fd788..d508183f9c 100644 --- a/documentation/public/user-guide/index.md +++ b/documentation/public/user-guide/index.md @@ -2,5 +2,5 @@ - [Introduction](./introduction.md) - [Concepts](./concepts.md) -- [Rust Crate](./rust-crate/index.md) +- [Tree Query Language](./tree-query-language.md) - [NPM Package](./npm-package/index.md) diff --git a/documentation/public/user-guide/introduction.md b/documentation/public/user-guide/introduction.md index 231ec50b6d..662607df37 100644 --- a/documentation/public/user-guide/introduction.md +++ b/documentation/public/user-guide/introduction.md @@ -24,4 +24,4 @@ This is why, instead of having to download separate versions of the tool for eac ## Distributions -Slang itself is written in Rust and we maintain a public Rust package on [crates.io](https://crates.io/crates/slang_solidity). At the moment, we also distribute it as an [npm package](https://www.npmjs.com/package/@nomicfoundation/slang) with TypeScript interface. In the future, we plan on expanding the language captures with Python and possibly more. +Slang itself is written in Rust, compiled as a WASM component, and distributed as an [npm package](https://www.npmjs.com/package/@nomicfoundation/slang) with a TypeScript interface. In the future, we are also looking into publishing it as a Rust crate, a Python library, and possibly more. diff --git a/documentation/public/user-guide/npm-package/using-queries.md b/documentation/public/user-guide/npm-package/using-queries.md index 89c53d1d4a..194770d35e 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](./../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. +The [Tree 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/.navigation.md b/documentation/public/user-guide/rust-crate/.navigation.md deleted file mode 100644 index 1d2ebe4cdd..0000000000 --- a/documentation/public/user-guide/rust-crate/.navigation.md +++ /dev/null @@ -1,6 +0,0 @@ -- [Rust Crate](./index.md) -- [Installation](./installation.md) -- [Using the CLI](./using-the-cli.md) -- [Using the Parser](./using-the-parser.md) -- [Using the Cursor](./using-the-cursor.md) -- [Using Queries](./using-queries.md) diff --git a/documentation/public/user-guide/rust-crate/index.md b/documentation/public/user-guide/rust-crate/index.md deleted file mode 100644 index d956e64aba..0000000000 --- a/documentation/public/user-guide/rust-crate/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Rust Crate - -- [Installation](./installation.md) -- [Using the CLI](./using-the-cli.md) -- [Using the Parser](./using-the-parser.md) -- [Using the Cursor](./using-the-cursor.md) -- [Using Queries](./using-queries.md) diff --git a/documentation/public/user-guide/rust-crate/installation.md b/documentation/public/user-guide/rust-crate/installation.md deleted file mode 100644 index 2adf831d8a..0000000000 --- a/documentation/public/user-guide/rust-crate/installation.md +++ /dev/null @@ -1,16 +0,0 @@ -# Installation - -The Rust package is published to crates.io as [`slang_solidity`](https://crates.io/crates/slang_solidity) ([docs](https://docs.rs/slang_solidity/latest/slang_solidity/)). -It can be used both as a regular Rust dependency and as a standalone CLI (installable with Cargo). - -You can install the CLI as a cargo binary using: - -```bash -cargo install "slang_solidity_cli" -``` - -Or you can add the API as a dependency to your project: - -```bash -cargo add "slang_solidity" -``` diff --git a/documentation/public/user-guide/rust-crate/using-queries.md b/documentation/public/user-guide/rust-crate/using-queries.md deleted file mode 100644 index 2c6e2639f1..0000000000 --- a/documentation/public/user-guide/rust-crate/using-queries.md +++ /dev/null @@ -1,83 +0,0 @@ -# Using Queries - -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](./../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)). - -## Creating and executing queries - -You can create a `Query` struct using `Query::parse`, which accepts a `&str`. These can be then used by `Cursor::query` to execute it. - -You can pass multiple queries to a cursor to and efficiently traverse the tree looking for matches. They will be executed concurrently, returning matches in the order they appear in input. - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:creating-a-query" -``` - -## Iterating over node patterns - -Queries allow you to iterate over all node patterns that match the query, which can replace your need for manual iteration via cursors or visitors. In order to get a `Cursor` that points to the matched node, you need to capture them with a name capture (`@capture_name`) to a specific node in the query pattern. - -Let's use this to list all the contract definitions in the source file: - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/using-the-cursor.sol" -``` - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:visiting-contracts" -``` - -### Multiple patterns simultaneously - -We can also intersperse multiple patterns in a single query, which will return all the matches for each pattern. This can be useful when you want to match multiple types of nodes in a single pass. - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:multiple-patterns" -``` - -## Matching on node's label - -We can match not only on the node's kind, but also on its label. This can be useful if there may be two children with the same kind but different labels or to be more declarative. - -To do so, we use `[label: _]` syntax. Here, we also use `_` to allow matching any kind of node, as long as it matches the given label. - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/typed-tuple.sol" -``` - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:matching-on-label" -``` - -## Matching on node's literal content - -Lastly, we can also match on the node's literal content. This can be useful when you want to match a specific identifier, string, or number. - -Let's say we prefer our code to be explicit and prefer using `uint256` instead of `uint`. To find all instances of the `uint` alias we could do the following: - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/typed-tuple.sol" -``` - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:matching-on-literal-value" -``` - -## Example: Finding `tx.origin` patterns - -As a more realistic example, let's say we want to write a linter that unconditionally lints against all [`tx.origin`](https://docs.soliditylang.org/en/latest/security-considerations.html#tx-origin) accesses. - -Let's use the motivating example from [https://soliditylang.org](https://docs.soliditylang.org/en/latest/security-considerations.html#tx-origin): - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/tx-origin.sol" -``` - -Now, we can above features to write a query that matches all `tx.origin` patterns: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_queries.rs:tx-origin" -``` diff --git a/documentation/public/user-guide/rust-crate/using-the-cli.md b/documentation/public/user-guide/rust-crate/using-the-cli.md deleted file mode 100644 index 60ffd5a629..0000000000 --- a/documentation/public/user-guide/rust-crate/using-the-cli.md +++ /dev/null @@ -1,132 +0,0 @@ -# Using the CLI - -## Parsing Source Files - -The `parse` command will take a path to a Solidity file, and a `--version` flag. -Specifying the correct version is important, as it will affect the grammar used to parse inputs. - -All parse errors are printed in a human-readable format; the command will succeed if there are no parse errors, and fail otherwise. - -```bash -$ slang_solidity parse --help - -Usage: slang_solidity parse [OPTIONS] --version - -Arguments: - - File path to the Solidity (*.sol) source file to parse - -Options: - -v, --version - The Solidity language version to use for parsing - --json - Print the concrete syntax tree as JSON - -h, --help - Print help -``` - -Here is an example of the JSON output it can print: - -```json -// A Nonterminal node -"Nonterminal": { - // Name of the nonterminal kind - "kind": "SourceUnit", - // Length of the nonterminal in Unicode code points, depending on the encoding used - "text_len": { - "utf8": 24, - "utf16": 24, - "char": 24 // de facto utf32 - }, - "children": [/* Nonterminal or Terminal nodes */] -} -// A Terminal node -"Terminal": { - // Name of the terminal kind - "kind": "PragmaKeyword", - // Literal value, taken from the source code - "text": "pragma" -} -``` - -## Inspecting JSON Output - -Now let's try to use that command to parse the following Solidity file, and inspect its contents: - -```solidity title="input.sol" -pragma solidity ^0.8.0; -``` - -```bash -slang_solidity parse --json --version "0.8.0" "input.sol" > "output.json" -``` - -Because the resulting structure is well-defined and recursive, we can use the popular `jq` tool to quickly analyze the resulting output: - -```bash -JQ_QUERY='recurse | select(.Terminal?) | .Terminal' -cat output.json | jq "$JQ_QUERY" -``` - -This gives us a flat list of the Terminal nodes: - -```json -{ - "kind": "PragmaKeyword", - "text": "pragma" -} -{ - "kind": "Whitespace", - "text": " " -} -{ - "kind": "SolidityKeyword", - "text": "solidity" -} -{ - "kind": "Whitespace", - "text": " " -} -{ - "kind": "Caret", - "text": "^" -} -{ - "kind": "VersionPragmaValue", - "text": "0" -} -{ - "kind": "Period", - "text": "." -} -{ - "kind": "VersionPragmaValue", - "text": "8" -} -{ - "kind": "Period", - "text": "." -} -{ - "kind": "VersionPragmaValue", - "text": "0" -} -{ - "kind": "Semicolon", - "text": ";" -} -{ - "kind": "EndOfLine", - "text": "\n" -} -``` - -Now, we can adapt the query to select the `text` fields of the nodes and concatenate them, -which gives us back the reconstructed source code! 🎉 - -```bash -$ JQ_QUERY='[recurse | select(.Terminal?) | .Terminal.text] | join("")' -$ cat output.json | jq "$JQ_QUERY" - -"pragma solidity ^0.8.0;\n" -``` diff --git a/documentation/public/user-guide/rust-crate/using-the-cursor.md b/documentation/public/user-guide/rust-crate/using-the-cursor.md deleted file mode 100644 index 2f6dd2dc7a..0000000000 --- a/documentation/public/user-guide/rust-crate/using-the-cursor.md +++ /dev/null @@ -1,75 +0,0 @@ -# Using the Cursor - -This guide will walk you through the basics of using a [CST cursor](../concepts.md#cst-cursors) in your project. -Let's start with this source file, that contains three contracts: - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/using-the-cursor.sol" -``` - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:imports" - ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:parse-input" -``` - -## Listing Contract Names - -The below example uses a cursor to list the names of all contracts in a source file: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:listing-contract-names" -``` - -## Visiting Only a Sub-tree - -In cases like the above, we needed to visit a sub-tree of the CST (to get the contract name). -But we also need to remember to return the cursor to its original position after each read, -which is inconvenient, and can lead to subtle bugs. - -To avoid this, we can use the `spawn()` API, -which cheaply creates a new cursor that starts at the given node, without copying the previous path history. -This lets us visit the sub-tree of each contract, without modifying the original cursor: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:visiting-sub-tree" -``` - -## Accessing Node Positions - -The `Cursor` API also tracks the position and range of the current node it is visiting. -Here is an example that records the source range of each contract, along with its text: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:accessing-node-positions" -``` - -## Using Iterator API - -In addition to the procedural-style methods, the `Cursor` struct also implements the `Iterator` trait, which allows you to use it in a functional style. - -Let's use that to extract all `Identifier` nodes from the source text using that API: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:using-iterator-api" -``` - -!!! note - - It's important to note that `Iterator::next` first visits the current node, - yields it, and then moves the cursor to the next node. - As such, accessor associated functions called on the `Cursor` that reference - the "current" will point to the one that is not yet yielded by the iterator. - This might be an important, when mixing the two styles. - -## Using a Cursor with Names - -In addition to the basic `Cursor`, there's also a `CursorWithLabels` type -that keeps track of the names of the nodes it visits. -You can create a `CursorWithLabels` from a `Cursor` by using the `with_labels()` API. - -Let's use that to extract all nodes that are labeled `Name`: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_cursor.rs:using-labeled-cursors" -``` diff --git a/documentation/public/user-guide/rust-crate/using-the-parser.md b/documentation/public/user-guide/rust-crate/using-the-parser.md deleted file mode 100644 index 6430730efa..0000000000 --- a/documentation/public/user-guide/rust-crate/using-the-parser.md +++ /dev/null @@ -1,48 +0,0 @@ -# Using the Parser - -Using the API directly provides us with a more fine-grained control over the parsing process. It allows us to parse not just the input as a top-level source unit, but also individual nonterminals like contracts, various definitions, and even expressions. - -## Parsing Source Files - -Let's start with this simple source file, that contains a single contract: - -```solidity title="input.sol" ---8<-- "documentation/public/user-guide/inputs/using-the-parser.sol" -``` - -We begin by creating a `Parser` object with a specified version. This is an entry point for our parser API. -Then we can use it to parse the source file, specifying the top-level nonterminal to parse: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:imports" - ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:parse-input" -``` - -## Checking for Syntax Errors - -If the file has errors, we can get them from the `ParseOutput` type, and print them out: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:print-errors" -``` - -Otherwise, we can check if input is valid using this helpful utility: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:assert-is-valid" -``` - -## Inspecting the Parse Tree - -Now, let's try to inspect the resulting CST, and iterate on its children: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:inspect-tree" -``` - -Additionally, we can convert the CST node back into the input string: - -```{ .rust } ---8<-- "crates/solidity/outputs/cargo/tests/src/doc_examples/using_the_parser.rs:unparse-node" -```