xdoc-rs 0.1.1

Declarative XML engine 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
136
137
138

use std::fmt;

/// Convenient result type for core XML operations.
pub type XmlResult<T> = Result<T, XmlError>;

/// High-level category for an XML engine error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ErrorKind {
    InvalidName,
    InvalidNamespace,
    DuplicateNamespacePrefix,
    UnknownNamespacePrefix,
    InvalidOperation,
    NotFound,
    Parse,
    Build,
    Query,
    Validation,
    Signature,
    Io,
}

/// Location in a source XML document, when known.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Span {
    line: Option<usize>,
    column: Option<usize>,
}

impl Span {
    /// Creates a span with a known one-based line and column.
    pub fn new(line: usize, column: usize) -> Self {
        Self {
            line: Some(line),
            column: Some(column),
        }
    }

    /// Creates a span for cases where the exact location is unavailable.
    pub fn unknown() -> Self {
        Self {
            line: None,
            column: None,
        }
    }

    pub fn line(&self) -> Option<usize> {
        self.line
    }

    pub fn column(&self) -> Option<usize> {
        self.column
    }
}

/// Structured error used by the XML engine.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct XmlError {
    kind: ErrorKind,
    message: String,
    span: Option<Span>,
}

impl XmlError {
    pub fn new(kind: ErrorKind, message: impl Into<String>) -> Self {
        Self {
            kind,
            message: message.into(),
            span: None,
        }
    }

    pub fn with_span(mut self, span: Span) -> Self {
        self.span = Some(span);
        self
    }

    pub fn invalid_name(name: impl AsRef<str>, reason: impl AsRef<str>) -> Self {
        Self::new(
            ErrorKind::InvalidName,
            format!("invalid XML name `{}`: {}", name.as_ref(), reason.as_ref()),
        )
    }

    pub fn kind(&self) -> &ErrorKind {
        &self.kind
    }

    pub fn message(&self) -> &str {
        &self.message
    }

    pub fn span(&self) -> Option<Span> {
        self.span
    }
}

impl fmt::Display for XmlError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self.span {
            Some(span) => match (span.line(), span.column()) {
                (Some(line), Some(column)) => {
                    write!(
                        f,
                        "{:?}: {} at line {}, column {}",
                        self.kind, self.message, line, column
                    )
                }
                _ => write!(f, "{:?}: {} at unknown location", self.kind, self.message),
            },
            None => write!(f, "{:?}: {}", self.kind, self.message),
        }
    }
}

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

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

    #[test]
    fn error_includes_kind_and_message() {
        let error = XmlError::new(ErrorKind::InvalidName, "bad name");

        assert_eq!(error.kind(), &ErrorKind::InvalidName);
        assert_eq!(error.message(), "bad name");
        assert_eq!(error.span(), None);
    }

    #[test]
    fn error_can_include_span() {
        let error = XmlError::new(ErrorKind::Parse, "unexpected token").with_span(Span::new(3, 9));

        assert_eq!(error.span(), Some(Span::new(3, 9)));
        assert!(error.to_string().contains("line 3, column 9"));
    }
}