docs: update docs to reflect usage of results (#207)

* docs: update docs to reflect usage of results

* chore: update installation instructions

* docs: add example request

* docs: fix request example

* docs: update summary

* docs: update result docs

* docs: update results example

* docs: update requests description

* chore: remove example request test

* docs: update fe docs

* Update docs/src/modules/requests.md

Co-authored-by: V <[email protected]>

---------

Co-authored-by: V <[email protected]>

README.md

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

docs/src/SUMMARY.md

@@ -23,6 +23,8 @@
     - [Strings](./modules/strings.md)
     - [Utils](./modules/utils.md)
     - [Watchers](./modules/watchers.md)
+    - [Results](./modules/results.md)
+    - [Requests](./modules/requests.md)
 
 # Reference
 

docs/src/guide/installation.md

@@ -2,5 +2,5 @@
 
 In an existing Foundry project, use `forge install`:
 ```
-$ forge install nomoixyz/vulcan@0.3.0
+$ forge install nomoixyz/vulcan@0.4.0
 ```

docs/src/modules/commands.md

@@ -1,7 +1,7 @@
 # Commands
 
 Execute external commands. The `ffi` setting must be enabled on `foundry.toml` for this module to
-work.
+work. The `commands` module uses [`Results`](./results.md) when returning values.
 
 ```solidity
 import { Test, Command, commands, CommandResult } from "vulcan/test.sol";

docs/src/modules/fe.md

@@ -16,7 +16,7 @@ contract TestMyContract is Test {
             .build()
             .unwrap();
 
-        bytes memory bytecode = fe.getBytecode("GuestBook");
+        bytes memory bytecode = fe.getBytecode("GuestBook").unwrap();
     }
 
 }

docs/src/modules/fs.md

@@ -4,34 +4,35 @@ Provides utilities to interact with the filesystem. In order to use this module
 `fs_permissions` setting must be set correctly in `foundry.toml`.
 
 ```solidity
-import { Test, fs } from "vulcan/test.sol";
+import { Test, fs, BytesResult } from "vulcan/test.sol";
 
 contract TestMyContract is Test {
     function testMyContract() external {
         // Write a string to a file
-        fs.write("test.txt", "Hello World");
+        fs.write("test.txt", "Hello World").unwrap();
 
         // Write bytes to a file
-        fs.writeBinary("test.bin", abi.encodeWithSignature("test(uint256)", 1e18));
+        fs.writeBinary("test.bin", abi.encodeWithSignature("test(uint256)", 1e18)).unwrap();
 
         // Read a file as a string
-        string memory content = fs.read("test.txt");
+        string memory content = fs.read("test.txt").unwrap();
 
         // Read a file as bytes
-        bytes memory binContent = fs.readBinary("test.bin");
+        BytesResult binContentResult = fs.readBinary("test.bin");
+        bytes memory binContent = binContentResult.unwrap();
 
         // Delete files
-        fs.remove("delete.me");
+        fs.remove("delete.me").unwrap();
 
         // Copy files
-        fs.copy("file.original", "file.backup");
+        fs.copy("file.original", "file.backup").unwrap();
 
         // Move files
-        fs.move("hold.txt", "hodl.txt");
+        fs.move("hold.txt", "hodl.txt").unwrap();
 
         // Check if a file or directory exists
-        if (fs.exists("some_file.txt")) {
-            fs.remove("some_file.txt");
+        if (fs.exists("some_file.txt").unwrap()) {
+            fs.remove("some_file.txt").unwrap();
         }
     }
 }

docs/src/modules/requests.md

@@ -0,0 +1,40 @@
+# Requests
+
+The request module is inspired by Rust's `reqwest` crate. It provides a flexible API to interact
+with external web services allowing to work with request headers, request authorization, response
+headers, parsing a response body as JSON and others.
+
+```solidity
+import { Test, request, RequestClient, ResponseResult, Response, JsonObject } from "vulcan/test.sol";
+
+contract HttpRequests is Test {
+    function getFoo() external returns (string memory) {
+        // Create a request client
+        RequestClient memory client = request.create().defaultHeader("Content-Type", "application/json");
+
+        // Send a GET request
+        ResponseResult responseResult = client.get("https://httpbin.org/get?foo=bar").send();
+
+        // Check if it's an error
+        if (responseResult.isError()) {
+            revert("Request to httpbin.org failed");
+        }
+
+        // Get the response from the response result
+        Response memory response = responseResult.toValue();
+
+        // Check status code
+        if (response.status == 401) {
+            revert("Request to httpbin.org is Unauthorized");
+        }
+
+        // Get the response body as a JsonObject
+        JsonObject memory jsonBody = response.json().unwrap();
+
+        // Get the value of `foo` from the json body response from httpbin
+        string memory foo = jsonBody.getString(".args.foo");
+
+        return foo;
+    }
+}
+```

docs/src/modules/results.md

@@ -0,0 +1,40 @@
+# Results
+
+The concept of "Results" is inspired by Rust. It centers around using specific types for returning values while also offering mechanisms to handle any potential errors.
+
+Similar to Rust's Results API, Vulcan implements the following functions for all result types:
+- `unwrap()`: if the Result is an Error, reverts with the default error message. If if is `Ok`, it returns the underlying value
+- `expect(message)`: same as `unwrap()`, but reverts with the provided error message
+- `isError()`: returns `true` if the `Result` is an error, `false` otherwise
+- `isOk()`: the oposite of `isError()`
+- `toError()`: transforms the Result into an `Error`
+- `toValue()`: gets the Result's underlying value (if the Result is Ok)
+
+```solidity
+import { Test, StringResult, Ok, console, CommandResult, Error } from "vulcan/test.sol";
+
+contract TestMyContract is Test {
+    function testMyContract() external {
+        CommandResult result = commands.run(["echo", "Hello, world!"]);
+
+        // We can handle different types of errors
+        if (result.isError()) {
+        Error err = result.toError();
+
+        if (err.matches(CommandError.NotExecuted)) {
+            revert("Something weird happened!");
+        } else {
+            revert("Unknown error");
+        }
+
+        // Or we could immediately get the actual output, reverting if the command failed to run
+        bytes memory out = result.expect("wtf echo failed!").stdout;
+
+        // Another way is to check if the result is ok
+        if (result.isOk()) {
+            // We know the result is ok so we can access the underlying value
+            out = result.toValue().stdout;
+        }
+    }
+}
+```

src/_modules/Commands.sol

@@ -161,15 +161,15 @@ library commands {
 
     /// @dev Runs a command using the specified `Command` struct as parameters and returns the result.
     /// @param self The `Command` struct that holds the parameters of the command.
-    /// @return The result of the command as a bytes array.
+    /// @return The result of the command wrapped in a `CommandResult`.
     function run(Command memory self) internal returns (CommandResult) {
         return self.inputs.run();
     }
 
     /// @dev Runs a command with the specified `inputs` as parameters and returns the result.
     /// @param inputs An array of strings representing the parameters of the command.
-    /// @return result The result of the command as a bytes array.
-    function run(string[] memory inputs) internal returns (CommandResult result) {
+    /// @return The result of the command wrapped in a `CommandResult`.
+    function run(string[] memory inputs) internal returns (CommandResult) {
         try vulcan.hevm.tryFfi(inputs) returns (VmSafe.FfiResult memory ffiResult) {
             CommandOutput memory output;
 

src/_modules/Fs.sol

@@ -23,9 +23,9 @@ library fs {
     using LibError for *;
     using FsErrors for Error;
 
-    /// @dev Reads the file on `path` and returns its content as a `string`.
+    /// @dev Reads the file on `path` and returns its content as a `StringResult`.
     /// @param path The path to the file.
-    /// @return The content of the file as `string`.
+    /// @return The content of the file as `StringResult`.
     function readFile(string memory path) internal view returns (StringResult) {
         try vulcan.hevm.readFile(path) returns (string memory content) {
             return Ok(content);
@@ -36,9 +36,9 @@ library fs {
         }
     }
 
-    /// @dev Reads the file on `path` and returns its content as a `bytes`.
+    /// @dev Reads the file on `path` and returns its content as a `BytesResult`.
     /// @param path The path to the file.
-    /// @return The content of the file as `bytes`.
+    /// @return The content of the file as `BytesResult`.
     function readFileBinary(string memory path) internal view returns (BytesResult) {
         try vulcan.hevm.readFileBinary(path) returns (bytes memory content) {
             return Ok(content);
@@ -50,7 +50,7 @@ library fs {
     }
 
     /// @dev Obtains the current project's root.
-    /// @return The current project's root.
+    /// @return The current project's root as `StringResult`.
     function projectRoot() internal view returns (StringResult) {
         try vulcan.hevm.projectRoot() returns (string memory path) {
             return Ok(path);
@@ -63,7 +63,7 @@ library fs {
 
     /// @dev Obtains the metadata of the specified file or directory.
     /// @param fileOrDir The path to the file or directory.
-    /// @return data The metadata of the file or directory.
+    /// @return data The metadata of the file or directory as `FsMetadataResult`.
     function metadata(string memory fileOrDir) internal view returns (FsMetadataResult) {
         try vulcan.hevm.fsMetadata(fileOrDir) returns (Hevm.FsMetadata memory md) {
             FsMetadata memory data;

src/_modules/Json.sol

@@ -245,7 +245,7 @@ library json {
     }
 
     /// @dev Creates a new JsonObject struct.
-    /// @return The JsonObject struct.
+    /// @return The JsonObject struct wrapped in a JsonResult.
     function create(string memory obj) internal returns (JsonResult) {
         if (!isValid(obj)) {
             return JsonError.Invalid().toJsonResult();

test/_modules/Fe.t.sol

@@ -37,7 +37,7 @@ contract FeTest is Test {
     function testCompile() external {
         fe.create().setFilePath("./test/mocks/guest_book.fe").setOutputDir("./test/fixtures/fe/output").setOverwrite(
             true
-        ).build();
+        ).build().unwrap();
 
         StringResult result = fs.readFile("./test/fixtures/fe/output/A/A.bin");