reportify 0.2.2

Typed error reports with structured diagnostic context, causes and contributing factors, configurable rendering, and panic capture.
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

//! Everything about a report other than its typed error.

#[cfg(feature = "spantrace")]
use tracing_error::SpanTrace;
#[cfg(feature = "spantrace")]
use tracing_error::SpanTraceStatus;

use crate::annotation::Annotation;
use crate::backtrace::Backtrace;
use crate::erased::ErasedReport;
use crate::location::SourceLocation;
use crate::value::Field;

/// Everything about a [`Report`](crate::Report) other than its typed error: the
/// narrative, structured fields, where and when it was created, its cause, and its
/// factors.
#[derive(Debug)]
pub struct Context {
    pub(crate) annotations: Vec<Annotation>,
    pub(crate) fields: Vec<Field>,
    pub(crate) location: SourceLocation,
    pub(crate) backtrace: Backtrace,
    #[cfg(feature = "spantrace")]
    pub(crate) spantrace: SpanTrace,
    pub(crate) cause: Option<ErasedReport>,
    pub(crate) factors: Vec<ErasedReport>,
}

impl Context {
    #[track_caller]
    pub(crate) fn capture() -> Self {
        Self {
            annotations: Vec::new(),
            fields: Vec::new(),
            location: SourceLocation::caller(),
            backtrace: Backtrace::capture(),
            #[cfg(feature = "spantrace")]
            spantrace: SpanTrace::capture(),
            cause: None,
            factors: Vec::new(),
        }
    }

    /// The report's narrative: messages and suggestions, in the order they were added.
    #[must_use]
    pub fn annotations(&self) -> &[Annotation] {
        &self.annotations
    }

    /// Structured fields attached to the report.
    #[must_use]
    pub fn fields(&self) -> &[Field] {
        &self.fields
    }

    /// Where the report was created.
    #[must_use]
    pub fn location(&self) -> &SourceLocation {
        &self.location
    }

    /// Captured backtrace, if backtraces are enabled (`RUST_BACKTRACE=1`).
    #[must_use]
    pub fn backtrace(&self) -> &Backtrace {
        &self.backtrace
    }

    /// Whether a backtrace was actually captured.
    #[must_use]
    pub fn has_backtrace(&self) -> bool {
        self.backtrace.is_captured()
    }

    /// Captured span trace.
    #[cfg(feature = "spantrace")]
    #[must_use]
    pub fn spantrace(&self) -> &SpanTrace {
        &self.spantrace
    }

    /// Whether a span trace was actually captured.
    #[cfg(feature = "spantrace")]
    #[must_use]
    pub fn has_spantrace(&self) -> bool {
        self.spantrace.status() == SpanTraceStatus::CAPTURED
    }

    /// The one report this report was escalated from, if any.
    ///
    /// Only ever set by [`Report::escalate`](crate::Report::escalate). There is no way to
    /// attach a cause to an already-existing report, only to derive a new report from an
    /// old one, so this is never ambiguous about whether the cause was actually
    /// necessary: it always was, since escalating is what produced this report in the
    /// first place.
    #[must_use]
    pub fn cause(&self) -> Option<&ErasedReport> {
        self.cause.as_ref()
    }

    /// Independent factors attached to this report, e.g., several validation failures
    /// found at once.
    ///
    /// Unlike [`Context::cause`], a factor makes no claim that it alone was necessary or
    /// sufficient for the report to exist. It is simply attached alongside it.
    #[must_use]
    pub fn factors(&self) -> &[ErasedReport] {
        &self.factors
    }
}