caexfer 0.1.0

Exchange linear finite-element meshes and results across CAE formats
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

use std::fmt;

/// An actionable failure with a stable machine-readable code.
///
/// Match on [`Self::code`] rather than the human-readable message. Source
/// locations, when known, use one-based physical line numbers.
///
/// # Examples
///
/// ```
/// use caexfer::Error;
/// let error = Error::new("E_SAMPLE", "bad field").at(4);
/// assert_eq!(error.code, "E_SAMPLE");
/// assert_eq!(error.line, Some(4));
/// assert_eq!(error.to_string(), "E_SAMPLE at line 4: bad field");
/// ```

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Error {
    /// Stable diagnostic identifier; callers should branch on this, not `message`.
    pub code: &'static str,

    /// Human-readable explanation; wording may change between releases.
    pub message: String,

    /// One-based physical source line, when available.
    pub line: Option<usize>,
}

impl Error {
    /// Build an error without a source location.
    pub fn new(code: &'static str, message: impl Into<String>) -> Self {
        Self {
            code,
            message: message.into(),
            line: None,
        }
    }

    /// Attach a one-based physical source line.
    #[must_use]
    pub fn at(mut self, line: usize) -> Self {
        self.line = Some(line);
        self
    }
}

impl fmt::Display for Error {
    /// Render the stable code, optional physical line, and human message.
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.code)?;
        if let Some(line) = self.line {
            write!(f, " at line {line}")?;
        }
        write!(f, ": {}", self.message)
    }
}

impl std::error::Error for Error {}

impl From<std::io::Error> for Error {
    /// Retain an I/O failure's explanation under caexfer's `E_IO` code.
    fn from(value: std::io::Error) -> Self {
        Self::new("E_IO", value.to_string())
    }
}

/// Result returned by caexfer operations.
pub type Result<T> = std::result::Result<T, Error>;

/// Severity of a scoped validation finding.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Severity {
    /// Information was omitted or could not be validated in this scope.
    Warning,

    /// The requested scoped operation cannot proceed.
    Error,
}

/// One finding from scoped validation.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Diagnostic {
    /// Whether the finding blocks the scoped operation.
    pub severity: Severity,

    /// Stable diagnostic identifier.
    pub code: &'static str,

    /// Human-readable explanation.
    pub message: String,

    /// One-based physical source line, when available.
    pub line: Option<usize>,
}

impl From<Error> for Diagnostic {
    /// Convert a blocking error into one scoped validation finding.
    fn from(error: Error) -> Self {
        Self {
            severity: Severity::Error,
            code: error.code,
            message: error.message,
            line: error.line,
        }
    }
}

/// Findings from validation of a documented subset, not solver correctness.
/// Warnings leave a report valid *within its stated scope*; errors do not.
/// The default report has no findings.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
pub struct ValidationReport {
    /// Findings in source order.
    pub diagnostics: Vec<Diagnostic>,
}

#[cfg(test)]
mod tests {
    use super::*;

    /// Include one-based source lines in formatted diagnostics.
    #[test]
    fn error_display_carries_line() {
        assert_eq!(
            Error::new("E_TEST", "bad field").at(3).to_string(),
            "E_TEST at line 3: bad field"
        );
    }
}