refactor: simplify downcasting logic with std::mem::transmute (#20)

Simplified the downcasting implementations by replacing pointer casting
logic with `std::mem::transmute`, ensuring type safety after matching.
Added tests to validate various downcasting behaviors for both owned and
trait-object error scenarios, improving overall reliability and test
coverage.

.github/dependabot.yml

@@ -0,0 +1,7 @@
+version: 2
+updates:
+- package-ecosystem: cargo
+  directory: "/"
+  schedule:
+    interval: daily
+  open-pull-requests-limit: 10

.github/workflows/coverage.yml

@@ -0,0 +1,38 @@
+name: coverage
+
+on:
+  # Trigger the workflow on push or pull request,
+  # but only for the master branch
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  release:
+    types:
+      - created
+
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    env:
+      CARGO_TERM_COLOR: always
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          target: x86_64-unknown-linux-gnu
+          toolchain: nightly
+          components: llvm-tools-preview
+      - name: Install cargo-llvm-cov
+        uses: taiki-e/install-action@cargo-llvm-cov
+      - name: Generate code coverage
+        run: cargo +nightly llvm-cov --all-features --workspace --codecov --doctests --output-path codecov.json
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
+          files: codecov.json
+          fail_ci_if_error: true

.github/workflows/gh-pages.yml

@@ -7,34 +7,19 @@ on:
 
 jobs:
   deploy:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
 
-      - name: Set CURRENT_TWO_WEEKS for use in cache keys
-        run: echo "::set-env name=CURRENT_TWO_WEEKS::$(($(date +%V) / 2))"
-
-      - name: Cache cargo registry
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/registry
-          key: ${{ runner.os }}-cargo-registry-${{ env.CURRENT_TWO_WEEKS }}
-
-      - name: Cache cargo index
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/git
-          key: ${{ runner.os }}-cargo-index-${{ env.CURRENT_TWO_WEEKS }}
-
-      - name: Cache mdbook binary
-        uses: actions/cache@v1
-        with:
-          path: ~/.cargo/bin/mdbook
-          key: ${{ runner.os }}-cargo-mdbook-${{ env.CURRENT_TWO_WEEKS }}
-
       - name: Build mdbook
         run: cargo install mdbook
 
+      - name: Build cargo-readme
+        run: cargo install cargo-readme
+
+      - name: Build README.md
+        run: cargo readme > README.md
+
       - name: Build
         run: mdbook build
 

.github/workflows/rust.yml

@@ -1,15 +1,72 @@
 name: Rust
 
-on: [push]
+on:
+  # Trigger the workflow on push or pull request,
+  # but only for the master branch
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+  release:
+    types:
+      - created
 
 jobs:
   build:
-
     runs-on: ubuntu-latest
-
+    strategy:
+      matrix:
+        version:
+          - 1.54.0
+          - stable
+          - beta
+          - nightly
     steps:
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v1
-    - name: Build
+      - name: Install toolchain
-      run: cargo build --verbose
+        uses: dtolnay/rust-toolchain@master
-    - name: Run tests
+        with:
-      run: cargo test --verbose
+          toolchain: ${{ matrix.version }}
+          profile: minimal
+      - name: Build
+        run: cargo build --verbose
+      - name: Run tests
+        run: cargo test --verbose
+      - name: Build --all-features
+        run: cargo build --verbose --all-features
+      - name: Run tests --all-features
+        run: cargo test --verbose --all-features
+
+  fmt:
+    name: cargo fmt
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          components: rustfmt
+          toolchain: stable
+          profile: minimal
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: fmt
+          args: --all -- --check
+
+  clippy:
+    name: cargo clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          components: clippy
+          toolchain: stable
+          profile: minimal
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          command: clippy
+          args: -- -D warnings

.travis.yml

@@ -1,22 +0,0 @@
-language: rust
-
-branches:
-  except:
-    - gh-pages
-
-rust:
-- stable
-- nightly
-
-os:
-- linux
-- windows
-
-script:
-- cargo build --all
-- cargo test --all
-
-matrix:
-  allow_failures:
-  - rust: nightly
-  fast_finish: true

Cargo.toml

@@ -1,9 +1,9 @@
 [package]
 name = "chainerror"
-version = "0.5.0"
+version = "1.0.0"
 authors = ["Harald Hoyer <harald@redhat.com>"]
 edition = "2018"
-license = "MIT/Apache-2.0"
+license = "MIT OR Apache-2.0"
 documentation = "https://docs.rs/chainerror"
 homepage = "https://haraldh.github.io/chainerror/"
 repository = "https://github.com/haraldh/chainerror"
@@ -16,10 +16,11 @@ exclude = [ ".gitignore", "examples/*", "booksrc/*", "book.toml",
             "theme/*", "git-deploy-branch.sh", ".travis.yml" ]
 
 [badges]
-travis-ci = { repository = "haraldh/chainerror" }
+# See https://doc.rust-lang.org/cargo/reference/manifest.html#the-badges-section
+github = { repository = "haraldh/chainerror", workflow = "Rust" }
+maintenance = { status = "actively-developed" }
+is-it-maintained-issue-resolution = { repository = "haraldh/chainerror" }
+is-it-maintained-open-issues = { repository = "haraldh/chainerror" }
 
-[features]
+[package.metadata.docs.rs]
-default = [ ]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
-no-fileline = []
-display-cause = []
-no-debug-cause = []

README.md

@@ -1,129 +1,186 @@
-# chainerror
-
-[![Build Status](https://travis-ci.org/haraldh/chainerror.svg?branch=master)](https://travis-ci.org/haraldh/chainerror)
 [![Crate](https://img.shields.io/crates/v/chainerror.svg)](https://crates.io/crates/chainerror)
 [![Rust Documentation](https://img.shields.io/badge/api-rustdoc-blue.svg)](https://docs.rs/chainerror/)
+[![Coverage Status](https://codecov.io/gh/haraldh/chainerror/branch/master/graph/badge.svg?token=HGLJFGA11B)](https://codecov.io/gh/haraldh/chainerror)
+![Maintenance](https://img.shields.io/badge/maintenance-activly--developed-brightgreen.svg)
 
-`chainerror` provides an error backtrace like `failure` without doing a real backtrace, so even after you `strip` your
+# chainerror
+
+`chainerror` provides an error backtrace without doing a real backtrace, so even after you `strip` your
 binaries, you still have the error backtrace.
 
-`chainerror` has no dependencies!
+Having nested function returning errors, the output doesn't tell where the error originates from.
 
-`chainerror` uses `.source()` of `std::error::Error` along with `line()!` and `file()!` to provide a nice debug error backtrace.
+```rust
-It encapsulates all types, which have `Display + Debug` and can store the error cause internally.
+use std::path::PathBuf;
 
-Along with the `ChainError<T>` struct, `chainerror` comes with some useful helper macros to save a lot of typing.
+type BoxedError = Box<dyn std::error::Error + Send + Sync>;
-
+fn read_config_file(path: PathBuf) -> Result<(), BoxedError> {
-Debug information is worth it!
+    // do stuff, return other errors
-
+    let _buf = std::fs::read_to_string(&path)?;
-Now continue reading the
+    // do stuff, return other errors
-[Tutorial](https://haraldh.github.io/chainerror/tutorial1.html)
-
-## Example:
-Output:
-
-~~~
-$ cargo run -q --example example
-Main Error Report: func1 error calling func2
-
-Error reported by Func2Error: func2 error: calling func3
-
-The root cause was: std::io::Error: Kind(
-    NotFound
-)
-
-Debug Error:
-examples/example.rs:45: func1 error calling func2
-Caused by:
-examples/example.rs:20: Func2Error(func2 error: calling func3)
-Caused by:
-examples/example.rs:13: Error reading 'foo.txt'
-Caused by:
-Kind(NotFound)
-~~~
-
-~~~rust,ignore
-use chainerror::*;
-use std::error::Error;
-use std::io;
-use std::result::Result;
-
-fn do_some_io() -> Result<(), Box<Error + Send + Sync>> {
-    Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-fn func3() -> Result<(), Box<Error + Send + Sync>> {
+fn process_config_file() -> Result<(), BoxedError> {
-    let filename = "foo.txt";
+    // do stuff, return other errors
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    let _buf = read_config_file("foo.txt".into())?;
-    Ok(())
+    // do stuff, return other errors
-}
-
-derive_str_cherr!(Func2Error);
-
-fn func2() -> ChainResult<(), Func2Error> {
-    func3().map_err(mstrerr!(Func2Error, "func2 error: calling func3"))?;
-    Ok(())
-}
-
-enum Func1Error {
-    Func2,
-    IO(String),
-}
-
-impl ::std::fmt::Display for Func1Error {
-    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
-        match self {
-            Func1Error::Func2 => write!(f, "func1 error calling func2"),
-            Func1Error::IO(filename) => write!(f, "Error reading '{}'", filename),
-        }
-    }
-}
-
-impl ::std::fmt::Debug for Func1Error {
-    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
-        write!(f, "{}", self)
-    }
-}
-
-fn func1() -> ChainResult<(), Func1Error> {
-    func2().map_err(|e| cherr!(e, Func1Error::Func2))?;
-    let filename = String::from("bar.txt");
-    do_some_io().map_err(|e| cherr!(e, Func1Error::IO(filename)))?;
     Ok(())
 }
 
 fn main() {
-    if let Err(e) = func1() {
+    if let Err(e) = process_config_file() {
-        match e.kind() {
+        eprintln!("Error:\n{:?}", e);
-            Func1Error::Func2 => eprintln!("Main Error Report: func1 error calling func2"),
-            Func1Error::IO(filename) => {
-                eprintln!("Main Error Report: func1 error reading '{}'", filename)
-            }
-        }
-
-        if let Some(e) = e.find_chain_cause::<Func2Error>() {
-            eprintln!("\nError reported by Func2Error: {}", e)
-        }
-
-        if let Some(e) = e.root_cause() {
-            let ioerror = e.downcast_ref::<io::Error>().unwrap();
-            eprintln!("\nThe root cause was: std::io::Error: {:#?}", ioerror);
-        }
-
-        eprintln!("\nDebug Error:\n{:?}", e);
     }
 }
+```
 
-~~~
+This gives the output:
+```console
+Error:
+Os { code: 2, kind: NotFound, message: "No such file or directory" }
+```
+and you have no idea where it comes from.
 
-## Features
 
-`no-fileline`
+With `chainerror`, you can supply a context and get a nice error backtrace:
-: completely turn off storing filename and line
 
-`display-cause`
+```rust
-: turn on printing a backtrace of the errors in `Display`
+use chainerror::Context as _;
+use std::path::PathBuf;
 
-`no-debug-cause`
+type BoxedError = Box<dyn std::error::Error + Send + Sync>;
-: turn off printing a backtrace of the errors in `Debug`
+fn read_config_file(path: PathBuf) -> Result<(), BoxedError> {
+    // do stuff, return other errors
+    let _buf = std::fs::read_to_string(&path).context(format!("Reading file: {:?}", &path))?;
+    // do stuff, return other errors
+    Ok(())
+}
+
+fn process_config_file() -> Result<(), BoxedError> {
+    // do stuff, return other errors
+    let _buf = read_config_file("foo.txt".into()).context("read the config file")?;
+    // do stuff, return other errors
+    Ok(())
+}
+
+fn main() {
+    if let Err(e) = process_config_file() {
+        eprintln!("Error:\n{:?}", e);
+    }
+}
+```
+
+with the output:
+```console
+Error:
+examples/simple.rs:14:51: read the config file
+Caused by:
+examples/simple.rs:7:47: Reading file: "foo.txt"
+Caused by:
+Os { code: 2, kind: NotFound, message: "No such file or directory" }
+```
+
+`chainerror` uses `.source()` of `std::error::Error` along with `#[track_caller]` and `Location` to provide a nice debug error backtrace.
+It encapsulates all types, which have `Display + Debug` and can store the error cause internally.
+
+Along with the `Error<T>` struct, `chainerror` comes with some useful helper macros to save a lot of typing.
+
+`chainerror` has no dependencies!
+
+Debug information is worth it!
+
+## Multiple Output Formats
+
+`chainerror` supports multiple output formats, which can be selected with the different format specifiers:
+
+* `{}`: Display
+```console
+func1 error calling func2
+```
+
+* `{:#}`: Alternative Display
+```console
+func1 error calling func2
+Caused by:
+  func2 error: calling func3
+Caused by:
+  (passed error)
+Caused by:
+  Error reading 'foo.txt'
+Caused by:
+  entity not found
+```
+
+* `{:?}`: Debug
+```console
+examples/example.rs:50:13: func1 error calling func2
+Caused by:
+examples/example.rs:25:13: Func2Error(func2 error: calling func3)
+Caused by:
+examples/example.rs:18:13: (passed error)
+Caused by:
+examples/example.rs:13:18: Error reading 'foo.txt'
+Caused by:
+Kind(NotFound)
+
+```
+
+* `{:#?}`: Alternative Debug
+```console
+Error<example::Func1Error> {
+    occurrence: Some(
+        "examples/example.rs:50:13",
+    ),
+    kind: func1 error calling func2,
+    source: Some(
+        Error<example::Func2Error> {
+            occurrence: Some(
+                "examples/example.rs:25:13",
+            ),
+            kind: Func2Error(func2 error: calling func3),
+            source: Some(
+                Error<chainerror::AnnotatedError> {
+                    occurrence: Some(
+                        "examples/example.rs:18:13",
+                    ),
+                    kind: (passed error),
+                    source: Some(
+                        Error<alloc::string::String> {
+                            occurrence: Some(
+                                "examples/example.rs:13:18",
+                            ),
+                            kind: "Error reading 'foo.txt'",
+                            source: Some(
+                                Kind(
+                                    NotFound,
+                                ),
+                            ),
+                        },
+                    ),
+                },
+            ),
+        },
+    ),
+}
+```
+
+## Tutorial
+
+Read the [Tutorial](https://haraldh.github.io/chainerror/tutorial1.html)
+
+## License
+
+Licensed under either of
+
+* Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or <https://www.apache.org/licenses/LICENSE-2.0>)
+* MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/licenses/MIT>)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally
+submitted for inclusion in the work by you, as defined in the Apache-2.0
+license, shall be dual licensed as above, without any additional terms or
+conditions.

booksrc/LICENSE-APACHE

@@ -0,0 +1 @@
+../LICENSE-APACHE

booksrc/LICENSE-MIT

@@ -0,0 +1 @@
+../LICENSE-MIT

booksrc/SUMMARY.md

@@ -5,7 +5,7 @@
 - [Simple String Errors](tutorial1.md)
 - [Simple Chained String Errors](tutorial2.md)
 - [Mapping Errors](tutorial3.md)
-- [Saving coding chars](tutorial4.md)
+- [More Information](tutorial4.md)
 - [The source() of Errors](tutorial5.md)
 - [Downcast the Errors](tutorial6.md)
 - [The root cause of all Errors](tutorial7.md)

booksrc/tutorial1.md

@@ -9,7 +9,7 @@ this only
 prints out the last `Error`.
 
 ~~~
-Error: StringError("func1 error")
+Error: "func1 error"
 ~~~
 
 The next chapters of this tutorial show how `chainerror` adds more information

booksrc/tutorial10.md

@@ -1,20 +1,16 @@
 # ErrorKind to the rescue
 
-To cope with different kind of errors, we introduce the kind of an error `Func1ErrorKind` with an enum.
+To cope with different kind of errors, we introduce the `kind` of an error `Func1ErrorKind` with an enum.
 
 Because we derive `Debug` and implement `Display` our `Func1ErrorKind` enum, this enum can be used as
 a `std::error::Error`.
 
-Not using `String` errors anymore, the `cherr!()` macro seen in the beginning of
-the tutorial has to be used again.
-
 Only returning `Func1ErrorKind` in `func1()` now let us get rid of `Result<(), Box<Error + Send + Sync>>` and we can
 use `ChainResult<(), Func1ErrorKind>`.
 
-In `main` we can now directly use the methods of `ChainError<T>` without downcasting the error first.
+In `main` we can now directly use the methods of `chainerror::Error<T>` without downcasting the error first.
 
-Also a nice `match` on `ChainError<T>.kind()` is now possible, which returns `&T`, meaning 
+Also, a nice `match` on `chainerror::Error<T>.kind()` is now possible, which returns `&T`, meaning `&Func1ErrorKind` here.
-`&Func1ErrorKind` here.
 
 ~~~rust
 {{#include ../examples/tutorial10.rs}}

booksrc/tutorial11.md

@@ -1,6 +1,6 @@
 # Debug for the ErrorKind
 
-One small improvement at the end of the tutorial is to fix the debug output of
+One small improvement is to fix the debug output of
 `Func1ErrorKind`. As you probably noticed, the output doesn't say much of the enum.
 
 ~~~
@@ -21,7 +21,7 @@ which gives us a lot more detail.
 
 To create your own Errors, you might find [crates](https://crates.io) which create enum `Display+Debug` via derive macros.
 
-Also noteworthy is [custom_error](https://crates.io/crates/custom_error) to define your custom errors,
+Also, noteworthy is [custom_error](https://crates.io/crates/custom_error) to define your custom errors,
 which can then be used with `chainerror`.
 
 ~~~rust

booksrc/tutorial12.md

@@ -1,6 +1,6 @@
 # Deref for the ErrorKind
 
-Because ChainError<T> implements Deref to &T, we can also match on `*e` instead of `e.kind()`
+Because chainerror::Error<T> implements Deref to &T, we can also match on `*e` instead of `e.kind()`
 or call a function with `&e`
 ~~~rust
 {{#include ../examples/tutorial12.rs}}

booksrc/tutorial13.md

@@ -1,6 +1,6 @@
 # Writing a library
 
-I would advise to only expose an `mycrate::ErrorKind` and type alias `mycrate::Error` to `ChainError<mycrate::ErrorKind>`
+I would advise to only expose an `mycrate::ErrorKind` and type alias `mycrate::Error` to `chainerror::Error<mycrate::ErrorKind>`
 so you can tell your library users to use the `.kind()` method as `std::io::Error` does.
 
 If you later decide to make your own `Error` implementation, your library users don't

booksrc/tutorial2.md

@@ -1,7 +1,7 @@
 # Simple Chained String Errors
 
-With relatively small changes and the help of the `cherr!` macro of the `chainerror` crate
+With relatively small changes and the help of the `context()` method of the `chainerror` crate
-the `String` errors are now chained together.
+the `&str` errors are now chained together.
 
 Press the play button in the upper right corner and see the nice debug output.
 
@@ -19,14 +19,13 @@ Press the play button in the upper right corner and see the nice debug output.
 {{#include ../examples/tutorial2.rs:13:15}}
 ~~~
 
-The macro `cherr!(olderror, newerror)` stores `olderror` as the source/cause of `newerror` 
+The function `context(newerror)` stores `olderror` as the source/cause of `newerror` 
-along with the filename (`file!()`) and line number (`line!()`)
+along with the `Location` of the `context()` call and returns `Err(newerror)`.
-and returns `newerror`.
 
-`Err()?` then returns the inner error applying `.into()`, so that we
+`?` then returns the inner error applying `.into()`, so that we
 again have a `Err(Box<Error + Send + Sync>)` as a result.
 
-The `Debug` implementation of `ChainError<T>` (which is returned by `cherr!()`)
+The `Debug` implementation of `chainerror::Error<T>` (which is returned by `context()`)
 prints the `Debug` of `T` prefixed with the stored filename and line number.
 
-`ChainError<T>` in our case is `ChainError<String>`.
+`chainerror::Error<T>` in our case is `chainerror::Error<&str>`.

booksrc/tutorial3.md

@@ -1,6 +1,6 @@
 # Mapping Errors
 
-Now let's get more rust idiomatic by using `.map_err()`.
+Now let's get more rust idiomatic by using `.context()` directly on the previous `Result`.
 
 ~~~rust
 {{#include ../examples/tutorial3.rs}}
@@ -14,13 +14,13 @@ If you compare the output to the previous example, you will see,
 that:
 
 ~~~
-Error: src/main.rs:19: "func1 error"
+Error: examples/tutorial2.rs:20:16: func1 error
 ~~~
 
 changed to just:
 
 ~~~
-src/main.rs:16: "func1 error"
+examples/tutorial3.rs:17:13: func1 error
 ~~~
 
 This is, because we caught the error of `func1()` in `main()` and print it out ourselves.

booksrc/tutorial4.md

@@ -1,12 +1,7 @@
-# Saving coding chars
+# More information
 
-Because decorating an error with more information should not
+To give more context to the error, you want to use `format!`
-let you jump through hoops, `chainerror` has a quick macro for that.
+to extend the information in the context string.
-
-`mstrerror!()` fits right into `.map_err()` letting you quickly add
-more debug strings.
-
-`mstrerror!()` even understands `format!()` syntax like `println!()`.
 
 ~~~rust
 {{#include ../examples/tutorial4.rs}}

booksrc/tutorial5.md

@@ -14,5 +14,4 @@ Sometimes you want to inspect the `source()` of an `Error`.
 Note, that because we changed the output of the error in `main()` from 
 `Debug` to `Display`, we don't see the error backtrace with filename and line number.
 
-To enable the `Display` backtrace, you have to enable the feature `display-cause` for `chainerror`.
+To use the `Display` backtrace, you have to use the alternative display format output `{:#}`.
- 

booksrc/tutorial7.md

@@ -4,15 +4,15 @@
 
 ~~~rust,ignore
 fn is_chain<T: 'static + Display + Debug>(&self) -> bool
-fn downcast_chain_ref<T: 'static + Display + Debug>(&self) -> Option<&ChainError<T>>
+fn downcast_chain_ref<T: 'static + Display + Debug>(&self) -> Option<&chainerror::Error<T>>
-fn downcast_chain_mut<T: 'static + Display + Debug>(&mut self) -> Option<&mut ChainError<T>>
+fn downcast_chain_mut<T: 'static + Display + Debug>(&mut self) -> Option<&mut chainerror::Error<T>>
 fn root_cause(&self) -> Option<&(dyn Error + 'static)>
 fn find_cause<U: Error + 'static>(&self) -> Option<&U>
-fn find_chain_cause<U: Error + 'static>(&self) -> Option<&ChainError<U>>
+fn find_chain_cause<U: Error + 'static>(&self) -> Option<&chainerror::Error<U>>
 fn kind<'a>(&'a self) -> &'a T
 ~~~
 
-Using `downcast_chain_ref::<String>()` gives a `ChainError<String>`, which can be used
+Using `downcast_chain_ref::<String>()` gives a `chainerror::Error<String>`, which can be used
 to call `.find_cause::<io::Error>()`. 
 
 ~~~rust,ignore

booksrc/tutorial8.md

@@ -1,14 +1,14 @@
 # Finding an Error cause
 
-To distinguish the errors occuring in various places, we can define named string errors with the
+To distinguish the errors occurring in various places, we can define named string errors with the
 "new type" pattern.
 
 ~~~rust,ignore
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
-derive_str_cherr!(Func1Error);
+chainerror::str_context!(Func1Error);
 ~~~
 
-Instead of `ChainError<String>` we now have `struct Func1Error(String)` and `ChainError<Func1Error>`.
+Instead of `chainerror::Error<String>` we now have `struct Func1Error(String)` and `chainerror::Error<Func1Error>`.
 
 In the `main` function you can see, how we can match the different errors.
 
@@ -18,9 +18,9 @@ Also see:
 ~~~
 as a shortcut to
 ~~~rust,ignore
-            if let Some(f2err) = f1err.find_cause::<ChainError<Func2Error>>() {
+            if let Some(f2err) = f1err.find_cause::<chainerror::Error<Func2Error>>() {
 ~~~
-hiding the `ChainError<T>` implementation detail.
+hiding the `chainerror::Error<T>` implementation detail.
 
 ~~~rust
 {{#include ../examples/tutorial8.rs}}

examples/example.rs

@@ -1,24 +1,28 @@
+use chainerror::Context as _;
 use std::error::Error;
+use std::fmt;
 use std::io;
-use std::result::Result;
-
-use chainerror::*;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-fn func3() -> Result<(), Box<dyn Error + Send + Sync>> {
+fn func4() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    do_some_io().context(format!("Error reading '{}'", filename))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+fn func3() -> Result<(), Box<dyn Error + Send + Sync>> {
+    func4().annotate()?;
+    Ok(())
+}
 
-fn func2() -> ChainResult<(), Func2Error> {
+chainerror::str_context!(Func2Error);
-    func3().map_err(mstrerr!(Func2Error, "func2 error: calling func3"))?;
+
+fn func2() -> chainerror::Result<(), Func2Error> {
+    func3().context(Func2Error::new("func2 error: calling func3"))?;
     Ok(())
 }
 
@@ -27,8 +31,8 @@ enum Func1Error {
     IO(String),
 }
 
-impl ::std::fmt::Display for Func1Error {
+impl fmt::Display for Func1Error {
-    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match self {
             Func1Error::Func2 => write!(f, "func1 error calling func2"),
             Func1Error::IO(filename) => write!(f, "Error reading '{}'", filename),
@@ -36,21 +40,29 @@ impl ::std::fmt::Display for Func1Error {
     }
 }
 
-impl ::std::fmt::Debug for Func1Error {
+impl fmt::Debug for Func1Error {
-    fn fmt(&self, f: &mut ::std::fmt::Formatter) -> ::std::fmt::Result {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         write!(f, "{}", self)
     }
 }
 
-fn func1() -> ChainResult<(), Func1Error> {
+fn func1() -> chainerror::Result<(), Func1Error> {
-    func2().map_err(|e| cherr!(e, Func1Error::Func2))?;
+    func2().context(Func1Error::Func2)?;
     let filename = String::from("bar.txt");
-    do_some_io().map_err(|e| cherr!(e, Func1Error::IO(filename)))?;
+    do_some_io().context(Func1Error::IO(filename))?;
     Ok(())
 }
 
 fn main() {
     if let Err(e) = func1() {
+        eprintln!("\nDisplay Error {{}}:\n{}", e);
+
+        eprintln!("\nAlternative Display Error {{:#}}:\n{:#}", e);
+
+        eprintln!("\nDebug Error {{:?}}:\n{:?}", e);
+
+        eprintln!("\nAlternative Debug Error {{:#?}}:\n{:#?}\n", e);
+
         match e.kind() {
             Func1Error::Func2 => eprintln!("Main Error Report: func1 error calling func2"),
             Func1Error::IO(filename) => {
@@ -66,7 +78,5 @@ fn main() {
             let ioerror = e.downcast_ref::<io::Error>().unwrap();
             eprintln!("\nThe root cause was: std::io::Error: {:#?}", ioerror);
         }
-
-        eprintln!("\nDebug Error:\n{:?}", e);
     }
 }

examples/tutorial1.rs

@@ -1,6 +1,8 @@
+#![allow(clippy::single_match)]
+#![allow(clippy::redundant_pattern_matching)]
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;

examples/tutorial10.rs

@@ -1,18 +1,18 @@
-use chainerror::*;
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+    do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
@@ -32,10 +32,10 @@ impl ::std::fmt::Display for Func1ErrorKind {
 }
 impl ::std::error::Error for Func1ErrorKind {}
 
-fn func1() -> ChainResult<(), Func1ErrorKind> {
+fn func1() -> chainerror::Result<(), Func1ErrorKind> {
-    func2().map_err(|e| cherr!(e, Func1ErrorKind::Func2))?;
+    func2().context(Func1ErrorKind::Func2)?;
     let filename = String::from("bar.txt");
-    do_some_io().map_err(|e| cherr!(e, Func1ErrorKind::IO(filename)))?;
+    do_some_io().context(Func1ErrorKind::IO(filename))?;
     Ok(())
 }
 
@@ -53,6 +53,8 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial11.rs

@@ -1,18 +1,18 @@
-use chainerror::*;
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+    do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
@@ -38,10 +38,10 @@ impl ::std::fmt::Debug for Func1ErrorKind {
 
 impl ::std::error::Error for Func1ErrorKind {}
 
-fn func1() -> ChainResult<(), Func1ErrorKind> {
+fn func1() -> chainerror::Result<(), Func1ErrorKind> {
-    func2().map_err(|e| cherr!(e, Func1ErrorKind::Func2))?;
+    func2().context(Func1ErrorKind::Func2)?;
     let filename = String::from("bar.txt");
-    do_some_io().map_err(|e| cherr!(e, Func1ErrorKind::IO(filename)))?;
+    do_some_io().context(Func1ErrorKind::IO(filename))?;
     Ok(())
 }
 
@@ -59,6 +59,8 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial12.rs

@@ -1,18 +1,18 @@
-use chainerror::*;
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+    do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
@@ -38,10 +38,10 @@ impl ::std::fmt::Debug for Func1ErrorKind {
 
 impl ::std::error::Error for Func1ErrorKind {}
 
-fn func1() -> ChainResult<(), Func1ErrorKind> {
+fn func1() -> chainerror::Result<(), Func1ErrorKind> {
-    func2().map_err(|e| cherr!(e, Func1ErrorKind::Func2))?;
+    func2().context(Func1ErrorKind::Func2)?;
     let filename = String::from("bar.txt");
-    do_some_io().map_err(|e| cherr!(e, Func1ErrorKind::IO(filename)))?;
+    do_some_io().context(Func1ErrorKind::IO(filename))?;
     Ok(())
 }
 
@@ -70,6 +70,8 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial13.rs

@@ -1,5 +1,9 @@
+#![allow(clippy::single_match)]
+#![allow(clippy::redundant_pattern_matching)]
+
 pub mod mycrate {
-    use chainerror::*;
+    use chainerror::Context as _;
+
     use std::io;
 
     fn do_some_io() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
@@ -7,11 +11,11 @@ pub mod mycrate {
         Ok(())
     }
 
-    derive_str_cherr!(Func2Error);
+    chainerror::str_context!(Func2Error);
 
     fn func2() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
         let filename = "foo.txt";
-        do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+        do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
         Ok(())
     }
 
@@ -21,7 +25,7 @@ pub mod mycrate {
         IO(String),
     }
 
-    derive_err_kind!(Error, ErrorKind);
+    chainerror::err_kind!(Error, ErrorKind);
 
     pub type Result<T> = std::result::Result<T, Error>;
 
@@ -35,9 +39,9 @@ pub mod mycrate {
     }
 
     pub fn func1() -> Result<()> {
-        func2().map_err(|e| cherr!(e, ErrorKind::Func2))?;
+        func2().context(ErrorKind::Func2)?;
         let filename = String::from("bar.txt");
-        do_some_io().map_err(|e| cherr!(e, ErrorKind::IO(filename)))?;
+        do_some_io().context(ErrorKind::IO(filename))?;
         Ok(())
     }
 }
@@ -72,6 +76,8 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial14.rs

@@ -1,7 +1,10 @@
+#![allow(clippy::single_match)]
+#![allow(clippy::redundant_pattern_matching)]
+
 pub mod mycrate {
     use std::error::Error as StdError;
 
-    use func2mod::{do_some_io, func2};
+    use self::func2mod::{do_some_io, func2};
 
     pub mod func2mod {
         use std::error::Error as StdError;
@@ -27,7 +30,7 @@ pub mod mycrate {
             }
         }
 
-        macro_rules! mcherr {
+        macro_rules! mcontext {
             ( $k:expr ) => {{
                 |e| {
                     Error(
@@ -92,7 +95,7 @@ pub mod mycrate {
 
         pub fn func2() -> std::result::Result<(), Error> {
             let filename = "foo.txt";
-            do_some_io().map_err(mcherr!(ErrorKind::IO(format!(
+            do_some_io().map_err(mcontext!(ErrorKind::IO(format!(
                 "Error reading '{}'",
                 filename
             ))))?;
@@ -115,7 +118,7 @@ pub mod mycrate {
         }
     }
 
-    macro_rules! mcherr {
+    macro_rules! mcontext {
         ( $k:expr ) => {{
             |e| {
                 Error(
@@ -175,9 +178,9 @@ pub mod mycrate {
     pub type Result<T> = std::result::Result<T, Error>;
 
     pub fn func1() -> Result<()> {
-        func2().map_err(mcherr!(ErrorKind::Func2))?;
+        func2().map_err(mcontext!(ErrorKind::Func2))?;
         let filename = String::from("bar.txt");
-        do_some_io().map_err(mcherr!(ErrorKind::IO(filename)))?;
+        do_some_io().map_err(mcontext!(ErrorKind::IO(filename)))?;
         Ok(())
     }
 }
@@ -212,6 +215,8 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial15.rs

@@ -1,19 +1,21 @@
-pub mod mycrate {
+#![allow(clippy::single_match)]
-    use std::io;
+#![allow(clippy::redundant_pattern_matching)]
 
-    use chainerror::*;
+pub mod mycrate {
+    use chainerror::{Context as _, ErrorDown as _};
+
+    use std::io;
 
     fn do_some_io(_f: &str) -> std::result::Result<(), io::Error> {
         Err(io::Error::from(io::ErrorKind::NotFound))?;
         Ok(())
     }
 
-    derive_str_cherr!(Func2Error);
+    chainerror::str_context!(Func2Error);
 
     fn func2() -> std::result::Result<(), Box<dyn std::error::Error + Send + Sync>> {
         let filename = "foo.txt";
-        do_some_io(filename)
+        do_some_io(filename).context(Func2Error(format!("Error reading '{}'", filename)))?;
-            .map_err(|e| cherr!(e, Func2Error(format!("Error reading '{}'", filename))))?;
         Ok(())
     }
 
@@ -25,7 +27,7 @@ pub mod mycrate {
         Unknown,
     }
 
-    derive_err_kind!(Error, ErrorKind);
+    chainerror::err_kind!(Error, ErrorKind);
     pub type Result<T> = std::result::Result<T, Error>;
 
     impl std::fmt::Display for ErrorKind {
@@ -82,21 +84,19 @@ pub mod mycrate {
     }
 
     pub fn func1() -> Result<()> {
-        func2().map_err(|e| cherr!(e, ErrorKind::from(&e)))?;
+        func2().map_err(|e| ErrorKind::from(&e))?;
 
         let filename = "bar.txt";
 
-        do_some_io(filename)
+        do_some_io(filename).map_context(|e| ErrorKind::from_io_error(e, filename.into()))?;
-            .map_err(|e| cherr!(e, ErrorKind::from_io_error(&e, filename.into())))?;
+        do_some_io(filename).map_context(|_| ErrorKind::IO(filename.into()))?;
-        do_some_io(filename).map_err(|e| cherr!(e, ErrorKind::IO(filename.into())))?;
+        do_some_io(filename).map_context(|e| ErrorKind::from(e))?;
-        do_some_io(filename).map_err(|e| cherr!(e, ErrorKind::from(&e)))?;
-        do_some_io(filename).map_err(minto_cherr!(ErrorKind))?;
 
         Ok(())
     }
 
     pub fn super_func1() -> Result<()> {
-        func1().map_err(minto_cherr!(ErrorKind))?;
+        func1().map_context(|e| ErrorKind::from(e))?;
         Ok(())
     }
 }
@@ -133,6 +133,8 @@ fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         }
 
         eprintln!("\nDebug Error:\n{:?}", e);
+
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial2.rs

@@ -1,8 +1,7 @@
-use chainerror::*;
+use chainerror::Context as _;
 
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -11,14 +10,14 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = do_some_io() {
-        Err(cherr!(e, "func2 error"))?;
+        Err(e).context("func2 error")?;
     }
     Ok(())
 }
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func2() {
-        Err(cherr!(e, "func1 error"))?;
+        Err(e).context("func1 error")?;
     }
     Ok(())
 }

examples/tutorial3.rs

@@ -1,8 +1,7 @@
-use chainerror::*;
+use chainerror::Context as _;
 
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -10,18 +9,19 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 }
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
-    do_some_io().map_err(|e| cherr!(e, "func2 error"))?;
+    do_some_io().context("func2 error")?;
     Ok(())
 }
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(|e| cherr!(e, "func1 error"))?;
+    func2().context("func1 error")?;
     Ok(())
 }
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func1() {
         eprintln!("{:?}", e);
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial4.rs

@@ -1,7 +1,7 @@
-use chainerror::*;
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -10,18 +10,19 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    do_some_io().context(format!("Error reading '{}'", filename))?;
     Ok(())
 }
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(mstrerr!("func1 error"))?;
+    func2().context("func1 error")?;
     Ok(())
 }
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func1() {
         eprintln!("{:?}", e);
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial5.rs

@@ -1,7 +1,7 @@
-use chainerror::*;
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -10,7 +10,7 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    do_some_io().context(format!("Error reading '{}'", filename))?;
     Ok(())
 }
 
@@ -18,7 +18,7 @@ fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func2() {
         if let Some(s) = e.source() {
             eprintln!("func2 failed because of '{}'", s);
-            Err(e).map_err(mstrerr!("func1 error"))?;
+            Err(e).context("func1 error")?;
         }
     }
     Ok(())
@@ -27,6 +27,7 @@ fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func1() {
         eprintln!("{}", e);
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial6.rs

@@ -1,7 +1,10 @@
-use chainerror::*;
+#![allow(clippy::single_match)]
+#![allow(clippy::redundant_pattern_matching)]
+
+use chainerror::Context as _;
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -10,12 +13,12 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    do_some_io().context(format!("Error reading '{}'", filename))?;
     Ok(())
 }
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(mstrerr!("func1 error"))?;
+    func2().context("func1 error")?;
     Ok(())
 }
 
@@ -35,6 +38,7 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
             }
             s = c;
         }
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial7.rs

@@ -1,7 +1,10 @@
-use chainerror::*;
+#![allow(clippy::single_match)]
+#![allow(clippy::redundant_pattern_matching)]
+
+use chainerror::{Context as _, ErrorDown as _};
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
@@ -10,12 +13,12 @@ fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!("Error reading '{}'", filename))?;
+    do_some_io().context(format!("Error reading '{}'", filename))?;
     Ok(())
 }
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(mstrerr!("func1 error"))?;
+    func2().context("func1 error")?;
     Ok(())
 }
 
@@ -36,6 +39,7 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
                 eprintln!("The root cause was: std::io::Error: {:#?}", ioerror);
             }
         }
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial8.rs

@@ -1,25 +1,25 @@
-use chainerror::*;
+use chainerror::{Context as _, ErrorDown as _};
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+    do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
-derive_str_cherr!(Func1Error);
+chainerror::str_context!(Func1Error);
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(mstrerr!(Func1Error, "func1 error"))?;
+    func2().context(Func1Error::new("func1 error"))?;
     Ok(())
 }
 
@@ -28,7 +28,7 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
         if let Some(f1err) = e.downcast_chain_ref::<Func1Error>() {
             eprintln!("Func1Error: {}", f1err);
 
-            if let Some(f2err) = f1err.find_cause::<ChainError<Func2Error>>() {
+            if let Some(f2err) = f1err.find_cause::<chainerror::Error<Func2Error>>() {
                 eprintln!("Func2Error: {}", f2err);
             }
 
@@ -36,6 +36,7 @@ fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
                 eprintln!("Debug Func2Error:\n{:?}", f2err);
             }
         }
+        std::process::exit(1);
     }
     Ok(())
 }

examples/tutorial9.rs

@@ -1,40 +1,41 @@
-use chainerror::*;
+use chainerror::{Context as _, ErrorDown};
+
 use std::error::Error;
 use std::io;
-use std::result::Result;
 
 fn do_some_io() -> Result<(), Box<dyn Error + Send + Sync>> {
     Err(io::Error::from(io::ErrorKind::NotFound))?;
     Ok(())
 }
 
-derive_str_cherr!(Func2Error);
+chainerror::str_context!(Func2Error);
 
 fn func2() -> Result<(), Box<dyn Error + Send + Sync>> {
     let filename = "foo.txt";
-    do_some_io().map_err(mstrerr!(Func2Error, "Error reading '{}'", filename))?;
+    do_some_io().context(Func2Error(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
-derive_str_cherr!(Func1ErrorFunc2);
+chainerror::str_context!(Func1ErrorFunc2);
-derive_str_cherr!(Func1ErrorIO);
+chainerror::str_context!(Func1ErrorIO);
 
 fn func1() -> Result<(), Box<dyn Error + Send + Sync>> {
-    func2().map_err(mstrerr!(Func1ErrorFunc2, "func1 error calling func2"))?;
+    func2().context(Func1ErrorFunc2::new("func1 error calling func2"))?;
     let filename = "bar.txt";
-    do_some_io().map_err(mstrerr!(Func1ErrorIO, "Error reading '{}'", filename))?;
+    do_some_io().context(Func1ErrorIO(format!("Error reading '{}'", filename)))?;
     Ok(())
 }
 
 fn main() -> Result<(), Box<dyn Error + Send + Sync>> {
     if let Err(e) = func1() {
-        if let Some(s) = e.downcast_ref::<ChainError<Func1ErrorIO>>() {
+        if let Some(s) = e.downcast_ref::<chainerror::Error<Func1ErrorIO>>() {
             eprintln!("Func1ErrorIO:\n{:?}", s);
         }
 
         if let Some(s) = e.downcast_chain_ref::<Func1ErrorFunc2>() {
             eprintln!("Func1ErrorFunc2:\n{:?}", s);
         }
+        std::process::exit(1);
     }
     Ok(())
 }

tests/test_basic.rs

@@ -0,0 +1,33 @@
+use chainerror::Context;
+
+#[test]
+fn test_basic() {
+    use std::path::PathBuf;
+    type BoxedError = Box<dyn std::error::Error + Send + Sync>;
+    fn read_config_file(path: PathBuf) -> Result<(), BoxedError> {
+        // do stuff, return other errors
+        let _buf = std::fs::read_to_string(&path).context(format!("Reading file: {:?}", &path))?;
+        // do stuff, return other errors
+        Ok(())
+    }
+    fn process_config_file() -> Result<(), BoxedError> {
+        // do stuff, return other errors
+        read_config_file("_non_existent.txt".into()).context("read the config file")?;
+        // do stuff, return other errors
+        Ok(())
+    }
+
+    if let Err(e) = process_config_file() {
+        let os_notfound_error = std::io::Error::from_raw_os_error(2);
+        let s = format!("{:?}", e);
+        let lines = s.lines().collect::<Vec<_>>();
+        assert_eq!(lines.len(), 5);
+        assert!(lines[0].starts_with("tests/test_basic.rs:"));
+        assert_eq!(lines[1], "Caused by:");
+        assert!(lines[2].starts_with("tests/test_basic.rs:"));
+        assert_eq!(lines[3], "Caused by:");
+        assert_eq!(lines[4], format!("{:?}", os_notfound_error));
+    } else {
+        panic!();
+    }
+}

tests/test_iter.rs

@@ -1,28 +1,54 @@
-use chainerror::*;
+use chainerror::Context;
 use std::error::Error;
-use std::fmt::Write;
 use std::io;
 
 #[test]
 fn test_iter() -> Result<(), Box<dyn Error + Send + Sync>> {
-    let err = io::Error::from(io::ErrorKind::NotFound);
+    use std::fmt::Write;
-    let err = cherr!(err, "1");
+    let err: Result<(), _> = Err(io::Error::from(io::ErrorKind::NotFound));
-    let err = cherr!(err, "2");
+    let err = err.context("1");
-    let err = cherr!(err, "3");
+    let err = err.context("2");
-    let err = cherr!(err, "4");
+    let err = err.context("3");
-    let err = cherr!(err, "5");
+    let err = err.context("4");
-    let err = cherr!(err, "6");
+    let err = err.context("5");
+    let err = err.context("6");
+    let err = err.err().unwrap();
 
     let mut res = String::new();
 
     for e in err.iter() {
-        write!(res, "{}", e.to_string())?;
+        write!(res, "{}", e)?;
     }
     assert_eq!(res, "654321entity not found");
 
     let io_error: Option<&io::Error> = err
         .iter()
-        .filter_map(Error::downcast_ref::<io::Error>)
+        .filter_map(<dyn Error>::downcast_ref::<io::Error>)
+        .next();
+
+    assert_eq!(io_error.unwrap().kind(), io::ErrorKind::NotFound);
+
+    Ok(())
+}
+
+#[test]
+fn test_iter_alternate() -> Result<(), Box<dyn Error + Send + Sync>> {
+    let err: Result<(), _> = Err(io::Error::from(io::ErrorKind::NotFound));
+    let err = err.context("1");
+    let err = err.context("2");
+    let err = err.context("3");
+    let err = err.context("4");
+    let err = err.context("5");
+    let err = err.context("6");
+    let err = err.err().unwrap();
+
+    let res = format!("{:#}", err);
+
+    assert_eq!(res, format!("6\nCaused by:\n  5\nCaused by:\n  4\nCaused by:\n  3\nCaused by:\n  2\nCaused by:\n  1\nCaused by:\n  {:#}", io::Error::from(io::ErrorKind::NotFound)));
+
+    let io_error: Option<&io::Error> = err
+        .iter()
+        .filter_map(<dyn Error>::downcast_ref::<io::Error>)
         .next();
 
     assert_eq!(io_error.unwrap().kind(), io::ErrorKind::NotFound);
@@ -32,13 +58,14 @@ fn test_iter() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 #[test]
 fn test_find_cause() -> Result<(), Box<dyn Error + Send + Sync>> {
-    let err = io::Error::from(io::ErrorKind::NotFound);
+    let err: Result<(), _> = Err(io::Error::from(io::ErrorKind::NotFound));
-    let err = cherr!(err, "1");
+    let err = err.context("1");
-    let err = cherr!(err, "2");
+    let err = err.context("2");
-    let err = cherr!(err, "3");
+    let err = err.context("3");
-    let err = cherr!(err, "4");
+    let err = err.context("4");
-    let err = cherr!(err, "5");
+    let err = err.context("5");
-    let err = cherr!(err, "6");
+    let err = err.context("6");
+    let err = err.err().unwrap();
 
     let io_error: Option<&io::Error> = err.find_cause::<io::Error>();
 
@@ -49,16 +76,17 @@ fn test_find_cause() -> Result<(), Box<dyn Error + Send + Sync>> {
 
 #[test]
 fn test_root_cause() -> Result<(), Box<dyn Error + Send + Sync>> {
-    let err = io::Error::from(io::ErrorKind::NotFound);
+    let err: Result<(), _> = Err(io::Error::from(io::ErrorKind::NotFound));
-    let err = cherr!(err, "1");
+    let err = err.context("1");
-    let err = cherr!(err, "2");
+    let err = err.context("2");
-    let err = cherr!(err, "3");
+    let err = err.context("3");
-    let err = cherr!(err, "4");
+    let err = err.context("4");
-    let err = cherr!(err, "5");
+    let err = err.context("5");
-    let err = cherr!(err, "6");
+    let err = err.context("6");
+    let err = err.err().unwrap();
 
     let err: Option<&(dyn std::error::Error + 'static)> = err.root_cause();
-    let io_error: Option<&io::Error> = err.and_then(Error::downcast_ref::<io::Error>);
+    let io_error: Option<&io::Error> = err.and_then(<dyn Error>::downcast_ref::<io::Error>);
 
     assert_eq!(io_error.unwrap().kind(), io::ErrorKind::NotFound);