# resext
**Main crate providing error handling with context chains**
This is the primary interface for ResExt. It re-exports the proc-macro as well as other helpers provided by ResExt.
---
## Installation
```toml
[dependencies]
resext = "1.0.0"
```
---
## Quick Example
```rust
use resext::resext;
#[resext]
enum FileError {
Io(std::io::Error),
Parse(serde_json::Error),
}
fn load_data(path: &str) -> Res<Data> {
let content = std::fs::read_to_string(path)
.context("Failed to read file")?;
let data = serde_json::from_str(&content)
.with_context(format_args!("Failed to parse {}", path))?;
Ok(data)
}
```
---
## Proc Macro
The proc macro provides clean syntax with full customization:
```rust
#[resext(
prefix = "ERROR: ",
suffix = "\n",
msg_prefix = " at: ",
msg_suffix = "",
delimiter = "\n",
source_prefix = "Caused by: ",
include_variant = true,
alias = MyResult,
alloc = true
)]
enum MyError {
Network(reqwest::Error),
Database { error: sqlx::Error },
}
```
### Attribute Options
- `prefix` - String prepended to entire error message
- `suffix` - String appended to entire error message
- `msg_prefix` - String prepended to each context message
- `msg_suffix` - String appended to each context message
- `delimiter` - Separator between context messages | default: " - " (NOTE: the delimiter always includes a newline before it, e.g. if delimiter = " - ", then messages will have "\n - " between them, not just " - ")
- `source_prefix` - String prepended to source error (default: "Error: ")
- `include_variant` - Include variant name in Display output (default: false)
- `alias` - Custom type alias name which is used for getting the names for other items generated by the proc-macro (default: `Res`)
- `buf_size` - Size for the context message byte buffer (default: 64)
- `alloc` Enable heap-spilling if context exceeds `buf_size`
---
# Context Methods
## `.context(self, msg: &str)`
Add static context to an error:
```rust
std::fs::read("file.txt")
.context("Failed to read file")?;
Ok::<(), ResErr>(())
```
## `.with_context(self, args: core::fmt::Arguments<'_>)`
Add dynamic context to an error:
```rust
let path = "file.txt";
std::fs::read(path)
.with_context(|| format!("Failed to read {}", path))?;
```
---
## Error Display Format
Errors are displayed with context chains:
```
Failed to load application
- Failed to read config file
- Failed to open file
Error: No such file or directory
```
With `include_variant = true`:
```
Failed to load application
- Failed to read config file
Error: Io: No such file or directory
```
---
## Examples
### Basic Error Handling
```rust
#[resext]
enum ConfigError {
Io(std::io::Error),
Parse(toml::de::Error),
}
fn load_config(path: &str) -> Res<Config> {
let content = std::fs::read_to_string(path)
.context("Failed to read config")?;
toml::from_str(&content)
.with_context(format_args!("Failed to parse {}", path))
}
```
### Multiple Error Types
```rust
#[resext(alias = ApiResult)]
enum ApiError {
Network(reqwest::Error),
Database(sqlx::Error),
Json(serde_json::Error),
}
async fn fetch_user(id: u64) -> ApiResult<User> {
let response = reqwest::get(format!("/users/{}", id))
.await
.context("Failed to fetch user")?;
let user = response.json()
.await
.context("Failed to parse user data")?;
Ok(user)
}
```
### Named Fields
```rust
#[resext]
enum DatabaseError {
Connection { error: sqlx::Error },
Query { error: sqlx::Error },
}
```
---
## Contributing
See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines.
---
## License
MIT - See [LICENSE](../LICENSE) for details.