anyhow

impl Error

// new 将 std Error 的错误转换为 anyhow::Error
pub fn new<E>(error: E) -> Self where E: StdError + Send + Sync + 'static

// 从 message 创建 anyhow::Error
pub fn msg<M>(message: M) -> Self where M: Display + Debug + Send + Sync + 'static

use anyhow::{Error, Result};
use futures::stream::{Stream, StreamExt, TryStreamExt};
async fn demo<S>(stream: S) -> Result<Vec<Output>> where S: Stream<Item = Input>
 {
    stream
        .then(ffi::do_some_work) // 返回 Result<Output, &str>
        .map_err(Error::msg)  // 将 Err(&str) 转换为 anyhow::Error
        // 返回 Result，如果 collect 过程中出错，则返回 Err(anyhow::Error)
        .try_collect()
        .await
 }


// 为 anyhow::Error 对象添加新的 context，一般传入的是字符串或错误值,
// 消耗自身，返回一个新的错误对象。
pub fn context<C>(self, context: C) -> Self
   where C: Display + Send + Sync + 'static

use anyhow::Result;
use std::fs::File;
use std::path::Path;

struct ParseError {
    line: usize,
    column: usize,
}

fn parse_impl(file: File) -> Result<T, ParseError> {
    //...
}

pub fn parse(path: impl AsRef<Path>) -> Result<T> {
    let file = File::open(&path)?;
    parse_impl(file).map_err(|error| {
        let context = format!( "only the first {} lines of {} are valid",
            error.line, path.as_ref().display(), );
        anyhow::Error::new(error).context(context)
    })
}

// 获得 Error 相关的 backtrace
pub fn backtrace(&self) -> &Backtrace

// An iterator of the chain of source errors contained by this Error.
// This iterator will visit every error in the cause chain of this error
// object, beginning with the error that this error object was created from.
pub fn chain(&self) -> Chain<'_>

use anyhow::Error;
use std::io;
pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
    for cause in error.chain() {
        if let Some(io_error) = cause.downcast_ref::<io::Error>() {
            return Some(io_error.kind());
        }
    }
    None
}

pub fn root_cause(&self) -> &(dyn StdError + 'static)

// Returns true if E is the type held by this error object.
pub fn is<E>(&self) -> bool where E: Display + Debug + Send + Sync + 'static,

// Attempt to downcast the error object to a concrete type.
pub fn downcast<E>(self) -> Result<E, Self>
  where E: Display + Debug + Send + Sync + 'static,

// Downcast this error object by reference.
pub fn downcast_ref<E>(&self) -> Option<&E>
  where E: Display + Debug + Send + Sync + 'static,

// If the error was caused by redaction, then return a tombstone instead of
// the content.
match root_cause.downcast_ref::<DataStoreError>() {
    Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
    None => Err(error),
}

use anyhow::{Context, Result};

// 使用 anyhow::Result<()> 作为函数返回值, 内部 Err 类型是 anyhow::Error
fn main() -> Result<()> {
    //...
    it.detach().context("Failed to detach the important thing")?;

    let content = std::fs::read(path).with_context(||
        format!("Failed to read instrs from {}", path))?;
    //...

    // 其它实现标准库 Error 的类型会被自动转换为 anyhow::Error
    let config = std::fs::read_to_string("cluster.json")?;
    let map: ClusterMap = serde_json::from_str(&config)?;
    println!("cluster info: {:#?}", map);
    Ok(())
}

pub trait Context<T, E>: Sealed {
    // 两个方法都会转移对象所有权，返回 any::Result 类型对象。
    // Required methods
    fn context<C>(self, context: C) -> Result<T, Error>
      where C: Display + Send + Sync + 'static;

    fn with_context<C, F>(self, f: F) -> Result<T, Error>
      where C: Display + Send + Sync + 'static, F: FnOnce() -> C;
}

// 示例:
use anyhow::{Context, Result};
use std::fs;
use std::path::PathBuf;

pub struct ImportantThing {
    path: PathBuf,
}

impl ImportantThing {
    pub fn detach(&mut self) -> Result<()> {...}
}

pub fn do_it(mut it: ImportantThing) -> Result<Vec<u8>> {
    // 为 Result 自动添加 context() 方法，返回 anyhow::Result<T> 类型对象
    it.detach().context("Failed to detach the important thing")?;
    let path = &it.path;

    // with_context() 方法使用一个闭包函数返回可显示的字符串，
    // 该方法返回 anyhow::Result<T> 类型对象
    let content = fs::read(path)
    .with_context(|| format!("Failed to read instrs from {}", path.display()))?;
    Ok(content)
}

// 后续打印 anyhow::Error 对象时, 会先返回 context()/with_context() 的内容,
// 然后是 Caused by 开始的未加 context 前的错误信息。

// Error: Failed to read instrs from ./path/to/instrs.json  // context() 信息

// Caused by:
//     No such file or directory (os error 2) // fs::read() 的报错信息

macro_rules! anyhow {
    ($msg:literal $(,)?) => { ... };
    ($err:expr $(,)?) => { ... };
    ($fmt:expr, $($arg:tt)*) => { ... };
}

use anyhow::{bail, Context, Result};
use std::fs;
use std::io::Read;
use thiserror::Error;

// 为自定义类型实现 thiserror::Error
#[derive(Clone, Debug, Eq, Error, PartialEq)]
// thiserror::Error drive macro 关联的 attribute macro
#[error("Found no username in {0}")]
struct EmptyUsernameError(String);

// 返回 anyhow::Result, 内部使用 anyhow::Error
fn read_username(path: &str) -> Result<String> {
    let mut username = String::with_capacity(100);
    fs::File::open(path)
        .with_context(|| format!("Failed to open {path}"))?
        .read_to_string(&mut username)
        .context("Failed to read")?; // anyhow::Context
    if username.is_empty() {
        bail!(EmptyUsernameError(path.to_string()));
    }
    Ok(username)
}

fn main() {
    //fs::write("config.dat", "").unwrap();
    match read_username("config.dat") {
        Ok(username) => println!("Username: {username}"),
        // 使用 anyhow::Error 自定义的 Debug 格式化输出.
        Err(err) => println!("Error: {err :?}"),
    }
}

use anyhow::{anyhow, Result};
fn lookup(key: &str) -> Result<V> {
    if key.len() != 16 {
        return Err(anyhow!("key length must be 16 characters, got {:?}", key));
    }
    // ...
}
if !has_permission(user, resource) {
    // 格式1: 格式化字符串
    bail!("permission denied for accessing {}", resource);
}
#[derive(Error, Debug)]
enum ScienceError {
    #[error("recursion limit exceeded")]
    RecursionLimitExceeded,
    ...
}
if depth > MAX_DEPTH {
    // 格式2: 实现 std::error:Error 的对象
    bail!(ScienceError::RecursionLimitExceeded);
}

// ensure!() 宏当 condition 不满足时，返回 anyhow::Result Error
ensure!(user == 0, "only user 0 is allowed");
#[derive(Error, Debug)]
enum ScienceError {
    #[error("recursion limit exceeded")]
    RecursionLimitExceeded,
    ...
}

ensure!(depth <= MAX_DEPTH, ScienceError::RecursionLimitExceeded);