use crate::any::Any;
use crate::fmt;
use crate::panic::Location;

/// 提供有关 panic 的信息的结构体。
///
/// `PanicInfo` 结构体被传递给由 [`set_hook`] 函数设置的 panic 钩子。
///
///
/// [`set_hook`]: ../../std/panic/fn.set_hook.html
///
/// # Examples
///
/// ```should_panic
/// use std::panic;
///
/// panic::set_hook(Box::new(|panic_info| {
///     println!("panic occurred: {panic_info}");
/// }));
///
/// panic!("critical system failure");
/// ```
#[lang = "panic_info"]
#[stable(feature = "panic_hooks", since = "1.10.0")]
#[derive(Debug)]
pub struct PanicInfo<'a> {
    payload: &'a (dyn Any + Send),
    message: Option<&'a fmt::Arguments<'a>>,
    location: &'a Location<'a>,
    can_unwind: bool,
}

impl<'a> PanicInfo<'a> {
    #[unstable(
        feature = "panic_internals",
        reason = "internal details of the implementation of the `panic!` and related macros",
        issue = "none"
    )]
    #[doc(hidden)]
    #[inline]
    pub fn internal_constructor(
        message: Option<&'a fmt::Arguments<'a>>,
        location: &'a Location<'a>,
        can_unwind: bool,
    ) -> Self {
        struct NoPayload;
        PanicInfo { location, message, payload: &NoPayload, can_unwind }
    }

    #[unstable(
        feature = "panic_internals",
        reason = "internal details of the implementation of the `panic!` and related macros",
        issue = "none"
    )]
    #[doc(hidden)]
    #[inline]
    pub fn set_payload(&mut self, info: &'a (dyn Any + Send)) {
        self.payload = info;
    }

    /// 返回与 panic 关联的有效载荷。
    ///
    /// 通常但并非总是 `&'static str` 或 [`String`]。
    ///
    /// [`String`]: ../../std/string/struct.String.html
    ///
    /// # Examples
    ///
    /// ```should_panic
    /// use std::panic;
    ///
    /// panic::set_hook(Box::new(|panic_info| {
    ///     if let Some(s) = panic_info.payload().downcast_ref::<&str>() {
    ///         println!("panic occurred: {s:?}");
    ///     } else {
    ///         println!("panic occurred");
    ///     }
    /// }));
    ///
    /// panic!("Normal panic");
    /// ```
    #[must_use]
    #[stable(feature = "panic_hooks", since = "1.10.0")]
    pub fn payload(&self) -> &(dyn Any + Send) {
        self.payload
    }

    /// 如果 `core` crate 中的 `panic!` 宏 (不是 `std` 中的) 与格式化字符串和一些其他参数一起使用，则返回该消息准备好与 [`fmt::write`] 一起使用
    ///
    ///
    #[must_use]
    #[unstable(feature = "panic_info_message", issue = "66745")]
    pub fn message(&self) -> Option<&fmt::Arguments<'_>> {
        self.message
    }

    /// 返回有关 panic 起源的位置的信息 (如果有)。
    ///
    /// 该方法当前将始终返回 [`Some`]，但是在 future 版本中可能会更改。
    ///
    ///
    /// # Examples
    ///
    /// ```should_panic
    /// use std::panic;
    ///
    /// panic::set_hook(Box::new(|panic_info| {
    ///     if let Some(location) = panic_info.location() {
    ///         println!("panic occurred in file '{}' at line {}",
    ///             location.file(),
    ///             location.line(),
    ///         );
    ///     } else {
    ///         println!("panic occurred but can't get location information...");
    ///     }
    /// }));
    ///
    /// panic!("Normal panic");
    /// ```
    ///
    #[must_use]
    #[stable(feature = "panic_hooks", since = "1.10.0")]
    pub fn location(&self) -> Option<&Location<'_>> {
        // NOTE: 如果将其更改为有时返回 None，请在 std::panicking::default_hook 和 core::panicking::panic_fmt 中处理这种情况。
        //
        Some(&self.location)
    }

    /// 返回是否允许 panic 处理程序从发生 panic 的点展开栈。
    ///
    /// 对于大多数类型的 panic 来说都是如此，除了试图从 `Drop` 实现或 ABI 不支持的函数展开引起的 panic 外。
    ///
    ///
    /// 即使此函数返回 false，panic 处理程序也可以安全地展开，但这只会导致再次调用 panic 处理程序。
    ///
    ///
    ///
    ///
    #[must_use]
    #[unstable(feature = "panic_can_unwind", issue = "92988")]
    pub fn can_unwind(&self) -> bool {
        self.can_unwind
    }
}

#[stable(feature = "panic_hook_display", since = "1.26.0")]
impl fmt::Display for PanicInfo<'_> {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str("panicked at ")?;
        if let Some(message) = self.message {
            write!(formatter, "'{}', ", message)?
        } else if let Some(payload) = self.payload.downcast_ref::<&'static str>() {
            write!(formatter, "'{}', ", payload)?
        }
        // NOTE: 我们不能使用 downcast_ref::<String>() 在这里，因为 String 在核心中不可用!
        // 当使用多个参数调用 `std::panic!` 时，有效载荷是一个字符串，但是在这种情况下，消息也是可用的。
        //
        //

        self.location.fmt(formatter)
    }
}