docs: add examples to some modules

README.md

@@ -19,7 +19,7 @@ Over time, Vulcan will grow to include more functionality and utilities, eventua
 ## Installation
 
 ```
-$ forge install nomoixyz/vulcan@v0.4.1
+$ forge install nomoixyz/vulcan@v0.4.2
 ```
 
 ## Usage

docs/src/OTHER_MODULES.md

@@ -0,0 +1,8 @@
+# Other modules
+
+- [Config](./modules/config.md)
+- [Console](./modules/console.md)
+- [Env](./modules/env.md)
+- [Events](./modules/events.md)
+- [Forks](./modules/forks.md)
+- [Strings](./modules/strings.md)

docs/src/SUMMARY.md

@@ -4,44 +4,28 @@
 
 - [Installation](./guide/installation.md)
 - [Testing](./testing/README.md)
-    - [Expect](./testing/expect.md)
 - [Scripts](./scripts/README.md)
-- [Using modules](./modules/README.md)
-    - [Accounts](./modules/accounts.md)
-    - [Commands](./modules/commands.md)
+
+# Modules
+
+- [Accounts](./modules/accounts.md)
+- [Commands](./modules/commands.md)
+- [Context](./modules/context.md)
+- [Expect](./modules/expect.md)
+- [Fe](./modules/fe.md)
+- [Format](./modules/fmt.md)
+- [Fs](./modules/fs.md)
+- [Gas](./modules/gas.md)
+- [Huff](./modules/huff.md)
+- [Json](./modules/json.md)
+- [Results \& Errors](./modules/results.md)
+- [Requests](./modules/requests.md)
+- [Utils](./modules/utils.md)
+- [Others](./OTHER_MODULES.md)
     - [Config](./modules/config.md)
     - [Console](./modules/console.md)
-    - [Context](./modules/context.md)
     - [Env](./modules/env.md)
     - [Events](./modules/events.md)
-    - [Fe](./modules/fe.md)
-    - [Format](./modules/fmt.md)
     - [Forks](./modules/forks.md)
-    - [Fs](./modules/fs.md)
-    - [Huff](./modules/huff.md)
-    - [Json](./modules/json.md)
     - [Strings](./modules/strings.md)
-    - [Utils](./modules/utils.md)
-    - [Watchers](./modules/watchers.md)
-    - [Results](./modules/results.md)
-    - [Requests](./modules/requests.md)
-
-# Reference
-
-- [Modules](./reference/modules/README.md)
-    - [Accounts](./reference/modules/accounts.md)
-    - [Commands](./reference/modules/commands.md)
-    - [Config](./reference/modules/config.md)
-    - [Context](./reference/modules/context.md)
-    - [Env](./reference/modules/env.md)
-    - [Events](./reference/modules/events.md)
-    - [Fe](./reference/modules/fe.md)
-    - [Format](./reference/modules/fmt.md)
-    - [Forks](./reference/modules/forks.md)
-    - [Fs](./reference/modules/fs.md)
-    - [Huff](./reference/modules/huff.md)
-    - [Invariants](./reference/modules/invariants.md)
-    - [Json](./reference/modules/json.md)
-    - [Strings](./reference/modules/strings.md)
-    - [Watchers](./reference/modules/watchers.md)
 

docs/src/examples/accounts/example.md

@@ -0,0 +1,109 @@
+## Examples
+### Create an address
+
+How to create a simple address
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample is Test {
+    function test() external {
+        address alice = accounts.create();
+
+        expect(alice).not.toEqual(address(0));
+    }
+}
+
+```
+
+### Create a labeled address
+
+Creating an address labeled as "Alice"
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample is Test {
+    function test() external {
+        address alice = accounts.create("Alice");
+
+        expect(alice).not.toEqual(address(0));
+    }
+}
+
+```
+
+### Create multiple addresses
+
+Creating multiple addresses
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample is Test {
+    function test() external {
+        address[] memory addresses = accounts.createMany(10);
+
+        expect(addresses.length).toEqual(10);
+    }
+}
+
+```
+
+### Create multiple labeled addresses with a prefix
+
+Creating multiple addresses labeled with the prefix `Account`
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample is Test {
+    function test() external {
+        address[] memory addresses = accounts.createMany(10, "Account");
+
+        expect(addresses.length).toEqual(10);
+    }
+}
+
+```
+
+### Use method chaining on addresses
+
+Use method chaining on addresses to call multiple methods
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample05 is Test {
+    using accounts for address;
+
+    function test() external {
+        address alice = accounts.create("Alice").setNonce(666).setBalance(100e18);
+
+        address bob = accounts.create("Bob").setBalance(10e18).impersonateOnce();
+
+        payable(alice).transfer(bob.balance);
+
+        expect(alice.balance).toEqual(110e18);
+        expect(alice.getNonce()).toEqual(666);
+        expect(bob.balance).toEqual(0);
+    }
+}
+
+```
+

docs/src/examples/commands/example.md

@@ -0,0 +1,57 @@
+## Examples
+### Run a simple command
+
+Run a simple command and obtain the output
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, commands, CommandResult, CommandOutput} from "vulcan/test.sol";
+
+contract RunCommandExample is Test {
+    function test() external {
+        // Run a command to get a result
+        CommandResult cmdResult = commands.run(["echo", "Hello, World!"]);
+
+        // Obtain the output from the result
+        CommandOutput memory output = cmdResult.expect("Failed to run command");
+
+        // Check the output
+        expect(string(output.stdout)).toEqual("Hello, World!");
+    }
+}
+
+```
+
+### Reuse a command
+
+Reuse a command with different arguments
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, commands, Command, CommandResult, CommandOutput} from "vulcan/test.sol";
+
+contract ReuseACommandExample is Test {
+    function test() external {
+        // Create a command
+        Command memory echo = commands.create("echo");
+
+        // Run the commands and get the results
+        CommandResult fooResult = echo.arg("foo").run();
+        CommandResult barResult = echo.arg("bar").run();
+
+        // Obtain the outputs from the results
+        CommandOutput memory fooOutput = fooResult.expect("Failed to run echo 'foo'");
+        CommandOutput memory barOutput = barResult.expect("Failed to run echo 'bar'");
+
+        // Check the outputs
+        expect(string(fooOutput.stdout)).toEqual("foo");
+        expect(string(barOutput.stdout)).toEqual("bar");
+    }
+}
+
+```
+

docs/src/examples/config/example.md

@@ -0,0 +1,69 @@
+## Examples
+### Obtain a specific RPC URL
+
+Read a specific RPC URL from the foundry configuration
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, config} from "vulcan/test.sol";
+
+contract ConfigExample is Test {
+    function test() external {
+        string memory key = "mainnet";
+
+        expect(config.rpcUrl(key)).toEqual("https://mainnet.rpc.io");
+    }
+}
+
+```
+
+### Obtain all the RPC URLs
+
+Read all the RPC URLs from the foundry configuration
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, config} from "vulcan/test.sol";
+
+contract ConfigExample is Test {
+    function test() external {
+        string[2][] memory rpcs = config.rpcUrls();
+
+        expect(rpcs.length).toEqual(2);
+        expect(rpcs[0][0]).toEqual("arbitrum");
+        expect(rpcs[0][1]).toEqual("https://arbitrum.rpc.io");
+        expect(rpcs[1][0]).toEqual("mainnet");
+        expect(rpcs[1][1]).toEqual("https://mainnet.rpc.io");
+    }
+}
+
+```
+
+### Obtain all the RPC URLs using structs
+
+Read all the RPC URL from the foundry configuration as structs
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, config, Rpc} from "vulcan/test.sol";
+
+contract ConfigExample is Test {
+    function test() external {
+        Rpc[] memory rpcs = config.rpcUrlStructs();
+
+        expect(rpcs.length).toEqual(2);
+        expect(rpcs[0].name).toEqual("arbitrum");
+        expect(rpcs[0].url).toEqual("https://arbitrum.rpc.io");
+        expect(rpcs[1].name).toEqual("mainnet");
+        expect(rpcs[1].url).toEqual("https://mainnet.rpc.io");
+    }
+}
+
+```
+

docs/src/examples/console/example.md

@@ -0,0 +1,33 @@
+## Examples
+### Log values
+
+Use the `console` function to log values.
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, console} from "vulcan/test.sol";
+
+contract ConsoleExample is Test {
+    function test() external pure {
+        string memory foo = "foo";
+        string memory bar = "bar";
+
+        uint256 oneTwoThree = 123;
+        uint256 threeTwoOne = 321;
+
+        bool isTrue = true;
+
+        console.log(foo);
+        console.log(foo, bar);
+        console.log(foo, bar, threeTwoOne);
+        console.log(foo, bar, threeTwoOne, isTrue);
+        console.log(threeTwoOne, oneTwoThree);
+        console.log(threeTwoOne + oneTwoThree);
+        console.log(1 > 0);
+    }
+}
+
+```
+