pi_result 0.2.0

Thin, typed, and observable Result aliases and error interoperability utilities
Documentation
#![cfg_attr(nightly, feature(error_generic_member_access))]
#![doc(html_no_source)]
#![doc = include_str!("../README.md")]

//! `pi_result` 的实现会按模块依赖从底向上逐步扩展。
//! 当前阶段已落地基础类型层与边界传播层的前半部分:
//! `kind`、`result`、`attachment`、`boundary`,以及观测/格式化/测试辅助与 `prelude`。

extern crate self as pi_result;

pub mod attachment;
pub mod boundary;
pub mod fmt;
pub mod inspect;
pub mod interop;
pub mod kind;
pub mod prelude;
pub mod result;
pub mod testing;

// 派生支持协议(derive support protocol)独立于上游补丁编号。
// 具体契约(contract)及冻结基线位于 docs/pi_result_api_design.md 的 derive-support-v1。
#[doc(hidden)]
#[path = "derive_support.rs"]
pub mod __derive_support_v1;

pub use error_stack;
pub use error_stack::{bail, ensure};
/// 兼容重导出入口(compatible re-export entry);普通使用推荐预导入(prelude)。
/// Error 派生(derive)来自配套宏库(companion macro crate),其它名字(names)沿上游导出(exports)。
pub mod thiserror {
    pub use ::thiserror::*;
    pub use pi_result_macros::Error;
}

pub use crate::boundary::{IntoErrorExt, IntoTypedContextExt};
pub use crate::fmt::{debug_message, user_message, verbose_message};
pub use crate::inspect::ErrorInspectExt;
pub use crate::interop::{
    ClassifyErrorKind, ExternalError, InteropResultExt, classify_io_error, source_type_name_of,
};
pub use crate::kind::ErrorKind;
pub use crate::prelude::*;
pub use crate::result::{Error, ErrorReport, RawResult, Result, TypedResult};

#[cfg(test)]
mod derive_entry_tests {
    #[derive(Debug, crate::ThisError)]
    #[error("crate-self derive")]
    struct Local;

    /// ENT-T4/T7:主库自身(runtime crate itself)不传覆盖属性(override attribute),真实 FoundCrate::Itself 路径(path)须可用。
    /// 核标准 Error/Display 与真实公共报告(standard Error-Display/public report),不以外部测试作用域(external-test scope)冒充库内作用域(crate-self scope)。
    #[test]
    fn test_crate_self_derive_resolves_the_private_self_alias() {
        let local = Local;
        let _: &dyn std::error::Error = &local;
        assert_eq!(local.to_string(), "crate-self derive");
        let report: crate::Error =
            crate::Report::new(local).change_context(crate::ErrorKind::Other);
        assert!(report.contains::<Local>());
        assert_eq!(report.current_context(), &crate::ErrorKind::Other);
    }
}