rootcause 0.12.1

A flexible, ergonomic, and inspectable error reporting library for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

//! Source code location attachment collector.
//!
//! This module provides functionality to automatically capture and attach
//! source code location information (file, line, column) to reports when they
//! are created.

use core::fmt;

use rootcause_internals::handlers::{AttachmentFormattingStyle, AttachmentHandler};

use crate::hooks::report_creation::AttachmentCollector;

/// Location in source code where a report was created.
///
/// This struct captures file and line information, typically used for
/// debugging and error tracking.
///
/// # Examples
///
/// ```
/// use rootcause::hooks::builtin_hooks::location::Location;
///
/// let loc = Location::caller();
/// println!("Error occurred at {}:{}", loc.file, loc.line);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Location {
    /// The source file path where the report was created.
    pub file: &'static str,
    /// The line number where the report was created.
    pub line: u32,
}

impl Location {
    /// Capture the caller's source code location.
    ///
    /// This function uses Rust's built-in `core::panic::Location::caller()` to
    /// obtain the file and line number of the code that invoked it.
    ///
    /// # Examples
    ///
    /// ```
    /// use rootcause::hooks::builtin_hooks::location::Location;
    ///
    /// let loc = Location::caller();
    /// assert!(loc.file.ends_with(".rs"));
    /// assert!(loc.line > 0);
    /// ```
    #[track_caller]
    pub const fn caller() -> Self {
        let location = core::panic::Location::caller();
        Location {
            file: location.file(),
            line: location.line(),
        }
    }
}

/// Implementation of [`fmt::Display`] for [`Location`]
///
/// Uses the formatting convetion of `filename:line`
impl fmt::Display for Location {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}:{}", self.file, self.line)
    }
}

/// Handler for formatting [`Location`] attachments.
///
/// This handler formats location information as `filename:line` for both
/// [`Display`] and [`Debug`] formatting.
///
/// # Examples
///
/// ```
/// use rootcause::{
///     hooks::builtin_hooks::location::{Location, LocationHandler},
///     prelude::*,
/// };
///
/// let report = report!("error").attach_custom::<LocationHandler, _>(Location::caller());
/// ```
///
/// [`Display`]: core::fmt::Display
/// [`Debug`]: core::fmt::Debug
#[derive(Copy, Clone)]
pub struct LocationHandler;
impl AttachmentHandler<Location> for LocationHandler {
    fn display(value: &Location, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        fmt::Display::fmt(value, formatter)
    }

    fn debug(value: &Location, formatter: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        fmt::Display::fmt(value, formatter)
    }

    fn preferred_formatting_style(
        _value: &Location,
        _report_formatting_function: rootcause_internals::handlers::FormattingFunction,
    ) -> AttachmentFormattingStyle {
        AttachmentFormattingStyle {
            placement: rootcause_internals::handlers::AttachmentFormattingPlacement::Inline,
            priority: 20,
            function: rootcause_internals::handlers::FormattingFunction::Display,
        }
    }
}

/// Attachment collector for capturing source code location information.
///
/// When registered as a report creation hook, this collector automatically
/// captures the source location where each report is created and attaches
/// it as a [`Location`] attachment.
///
/// ## Example
///
/// ```
/// use rootcause::hooks::{Hooks, builtin_hooks::location::LocationHook};
///
/// // Install hooks with location collector
/// Hooks::new()
///     .attachment_collector(LocationHook)
///     .install()
///     .ok();
/// ```
#[derive(Copy, Clone)]
pub struct LocationHook;

impl AttachmentCollector<Location> for LocationHook {
    type Handler = LocationHandler;

    fn collect(&self) -> Location {
        Location::caller()
    }
}