Skip to main content

quill/
topic.rs

1//! Hierarchical topic paths.
2
3use std::fmt;
4
5/// Default segment delimiter (MQTT-style).
6pub const DEFAULT_DELIMITER: char = '/';
7
8/// Error returned when parsing a [`Topic`] or [`Pattern`](crate::Pattern).
9#[derive(Debug, Clone, PartialEq, Eq)]
10pub enum ParseError {
11    /// The input string was empty.
12    Empty,
13    /// A segment was empty (leading, trailing, or doubled delimiter).
14    EmptySegment,
15    /// A multi-level wildcard (`#`) appeared somewhere other than the final segment.
16    MultiLevelNotFinal,
17}
18
19impl fmt::Display for ParseError {
20    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
21        match self {
22            Self::Empty => write!(f, "topic or pattern must not be empty"),
23            Self::EmptySegment => {
24                write!(f, "empty segment (leading, trailing, or doubled delimiter)")
25            }
26            Self::MultiLevelNotFinal => {
27                write!(f, "multi-level wildcard '#' must be the final segment")
28            }
29        }
30    }
31}
32
33impl std::error::Error for ParseError {}
34
35/// A hierarchical topic path made of non-empty segments.
36///
37/// Topics never contain wildcards; use [`Pattern`](crate::Pattern) for filters.
38///
39/// # Examples
40///
41/// ```
42/// use quill::Topic;
43///
44/// let topic = Topic::parse("sensors/kitchen/temp").unwrap();
45/// assert_eq!(topic.segments(), &["sensors", "kitchen", "temp"]);
46/// ```
47#[derive(Debug, Clone, PartialEq, Eq, Hash)]
48pub struct Topic {
49    segments: Vec<String>,
50    delimiter: char,
51}
52
53impl Topic {
54    /// Parse `input` using the [default delimiter](DEFAULT_DELIMITER).
55    pub fn parse(input: &str) -> Result<Self, ParseError> {
56        Self::parse_with(input, DEFAULT_DELIMITER)
57    }
58
59    /// Parse `input` using a custom segment `delimiter`.
60    pub fn parse_with(input: &str, delimiter: char) -> Result<Self, ParseError> {
61        let segments = split_segments(input, delimiter)?;
62        Ok(Self {
63            segments,
64            delimiter,
65        })
66    }
67
68    /// Borrowed topic segments in order.
69    pub fn segments(&self) -> &[String] {
70        &self.segments
71    }
72
73    /// The delimiter used when this topic was parsed.
74    pub fn delimiter(&self) -> char {
75        self.delimiter
76    }
77}
78
79impl TryFrom<&str> for Topic {
80    type Error = ParseError;
81
82    fn try_from(value: &str) -> Result<Self, Self::Error> {
83        Self::parse(value)
84    }
85}
86
87impl fmt::Display for Topic {
88    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
89        for (i, seg) in self.segments.iter().enumerate() {
90            if i > 0 {
91                write!(f, "{}", self.delimiter)?;
92            }
93            write!(f, "{seg}")?;
94        }
95        Ok(())
96    }
97}
98
99/// Split `input` on `delimiter`, rejecting empty input and empty segments.
100pub(crate) fn split_segments(input: &str, delimiter: char) -> Result<Vec<String>, ParseError> {
101    if input.is_empty() {
102        return Err(ParseError::Empty);
103    }
104
105    let mut segments = Vec::new();
106    for part in input.split(delimiter) {
107        if part.is_empty() {
108            return Err(ParseError::EmptySegment);
109        }
110        segments.push(part.to_owned());
111    }
112    Ok(segments)
113}
114
115#[cfg(test)]
116mod tests {
117    use super::*;
118
119    #[test]
120    fn parse_happy_path() {
121        let t = Topic::parse("sensors/kitchen/temp").unwrap();
122        assert_eq!(t.segments(), &["sensors", "kitchen", "temp"]);
123        assert_eq!(t.delimiter(), '/');
124        assert_eq!(t.to_string(), "sensors/kitchen/temp");
125    }
126
127    #[test]
128    fn parse_single_segment() {
129        let t = Topic::parse("sensors").unwrap();
130        assert_eq!(t.segments(), &["sensors"]);
131    }
132
133    #[test]
134    fn parse_custom_delimiter() {
135        let t = Topic::parse_with("a.b.c", '.').unwrap();
136        assert_eq!(t.segments(), &["a", "b", "c"]);
137        assert_eq!(t.delimiter(), '.');
138        assert_eq!(t.to_string(), "a.b.c");
139    }
140
141    #[test]
142    fn reject_empty() {
143        assert_eq!(Topic::parse(""), Err(ParseError::Empty));
144    }
145
146    #[test]
147    fn reject_leading_delimiter() {
148        assert_eq!(Topic::parse("/a"), Err(ParseError::EmptySegment));
149    }
150
151    #[test]
152    fn reject_trailing_delimiter() {
153        assert_eq!(Topic::parse("a/"), Err(ParseError::EmptySegment));
154    }
155
156    #[test]
157    fn reject_doubled_delimiter() {
158        assert_eq!(Topic::parse("a//b"), Err(ParseError::EmptySegment));
159    }
160
161    #[test]
162    fn try_from_str() {
163        let t = Topic::try_from("x/y").unwrap();
164        assert_eq!(t.segments(), &["x", "y"]);
165    }
166}