docs: add examples to some modules

docs/src/OTHER_MODULES.md

@@ -0,0 +1,14 @@
+# Other modules
+
+- [Config](./modules/config.md)
+- [Console](./modules/console.md)
+- [Context](./modules/context.md)
+- [Env](./modules/env.md)
+- [Events](./modules/events.md)
+- [Fe](./modules/fe.md)
+- [Forks](./modules/forks.md)
+- [Fs](./modules/fs.md)
+- [Huff](./modules/huff.md)
+- [Strings](./modules/strings.md)
+- [Utils](./modules/utils.md)
+- [Watchers](./modules/watchers.md)

docs/src/SUMMARY.md

@@ -4,27 +4,30 @@
 
 - [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)
+- [Expect](./modules/expect.md)
+- [Format](./modules/fmt.md)
+- [Json](./modules/json.md)
+- [Results \& Errors](./modules/results.md)
+- [Requests](./modules/requests.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
 

docs/src/examples/accounts/example.md

@@ -0,0 +1,109 @@
+## Examples
+### Create an address
+
+This example shows how to create an address
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample01 is Test {
+    function test() external {
+        address alice = accounts.create();
+
+        expect(alice).not.toEqual(address(0));
+    }
+}
+
+```
+
+### Create a labeled address
+
+This example shows how to create an address labeled as "Alice"
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample02 is Test {
+    function test() external {
+        address alice = accounts.create("Alice");
+
+        expect(alice).not.toEqual(address(0));
+    }
+}
+
+```
+
+### Create multiple addresses
+
+This example shows how to create multiple addresses
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect, accounts} from "vulcan/test.sol";
+
+contract AccountsExample03 is Test {
+    function test() external {
+        address[] memory addresses = accounts.createMany(10);
+
+        expect(addresses.length).toEqual(10);
+    }
+}
+
+```
+
+### Create multiple labeled addresses with a prefix
+
+This example shows how to create 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 AccountsExample04 is Test {
+    function test() external {
+        address[] memory addresses = accounts.createMany(10, "Account");
+
+        expect(addresses.length).toEqual(10);
+    }
+}
+
+```
+
+### Use method chaining on addresses
+
+This example shows how to use method chaining on addresses
+
+```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
+
+This example shows how to 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
+
+This example shows how 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/expect/example.md

@@ -0,0 +1,37 @@
+## Examples
+### Use different matchers
+
+This example shows how to use the `expect` function and its different matchers
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, expect} from "vulcan/test.sol";
+
+contract ExpectExample01 is Test {
+    function test() external {
+        expect(string("foo")).toEqual(string("foo"));
+        expect(string("foo")).not.toEqual(string("bar"));
+        expect(string("foo bar")).toContain(string("foo"));
+        expect(string("foo bar")).toContain(string("bar"));
+
+        expect(uint256(1)).toEqual(uint256(1));
+        expect(uint256(1)).not.toEqual(uint256(0));
+        expect(uint256(1)).toBeGreaterThan(uint256(0));
+        expect(uint256(1)).toBeGreaterThanOrEqual(uint256(1));
+        expect(uint256(0)).toBeLessThan(uint256(1));
+        expect(uint256(0)).toBeLessThanOrEqual(uint256(0));
+
+        expect(address(1)).toEqual(address(1));
+        expect(address(1)).not.toEqual(address(0));
+
+        expect(true).toBeTrue();
+        expect(false).toBeFalse();
+        expect((10 % 5) == 0).toBeTrue();
+        expect((10 % 6) == 4).toBeTrue();
+    }
+}
+
+```
+

docs/src/examples/format/example.md

@@ -0,0 +1,51 @@
+## Examples
+### Using templates
+
+This example shows how to use templates with the `format` module
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, accounts, expect, fmt} from "vulcan/test.sol";
+
+contract FormatExample01 is Test {
+    using accounts for address;
+
+    function test() external {
+        address target = address(1).setBalance(1);
+        uint256 balance = target.balance;
+
+        expect(fmt.format("The account {address} has {uint} wei", abi.encode(target, balance))).toEqual(
+            "The account 0x0000000000000000000000000000000000000001 has 1 wei"
+        );
+    }
+}
+
+```
+
+### Formatting decimals
+
+This example shows how to use the `{uint:dx}` placeholder to format numbers with decimals
+
+```solidity
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.13;
+
+import {Test, accounts, expect, fmt} from "vulcan/test.sol";
+
+contract FormatExample02 is Test {
+    using accounts for address;
+
+    function test() external {
+        address target = address(1).setBalance(1e17);
+        uint256 balance = target.balance;
+
+        expect(fmt.format("The account {address} has {uint:d18} eth", abi.encode(target, balance))).toEqual(
+            "The account 0x0000000000000000000000000000000000000001 has 0.1 eth"
+        );
+    }
+}
+
+```
+