rd-ast 0.0.1

Canonical, producer-agnostic AST for R's Rd (documentation) format
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

use std::fmt;

/// A human-oriented structural path through a producer's Rd object tree.
///
/// The [`fmt::Display`] representation is intended for diagnostics, not as a
/// machine-readable protocol.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RdPath {
    segments: Vec<RdPathSegment>,
}

impl RdPath {
    pub fn new(segments: Vec<RdPathSegment>) -> Self {
        Self { segments }
    }

    pub fn segments(&self) -> &[RdPathSegment] {
        &self.segments
    }

    pub fn with_child(&self, index: usize) -> RdPath {
        let mut path = self.clone();
        path.segments.push(RdPathSegment::Child(index));
        path
    }

    pub fn with_option(&self) -> RdPath {
        let mut path = self.clone();
        path.segments.push(RdPathSegment::Option);
        path
    }

    pub(crate) fn with_character(&self, index: usize) -> RdPath {
        let mut path = self.clone();
        path.segments.push(RdPathSegment::CharacterElement(index));
        path
    }
}

impl From<Vec<RdPathSegment>> for RdPath {
    fn from(segments: Vec<RdPathSegment>) -> Self {
        Self::new(segments)
    }
}

impl fmt::Display for RdPath {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        for (index, segment) in self.segments.iter().enumerate() {
            if index != 0 {
                f.write_str(" / ")?;
            }
            segment.fmt(f)?;
        }
        Ok(())
    }
}

#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum RdPathSegment {
    TopLevel(usize),
    Child(usize),
    Option,
    Attribute(String),
    AttributeValue,
    ListElement(usize),
    CharacterElement(usize),
}

impl fmt::Display for RdPathSegment {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::TopLevel(index) => write!(f, "top-level[{index}]"),
            Self::Child(index) => write!(f, "child[{index}]"),
            Self::Option => f.write_str("@option"),
            Self::Attribute(name) => write!(f, "@attr({name})"),
            Self::AttributeValue => f.write_str("value"),
            Self::ListElement(index) => write!(f, "list[{index}]"),
            Self::CharacterElement(index) => write!(f, "character[{index}]"),
        }
    }
}

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

    #[test]
    fn displays_structural_paths() {
        let path = RdPath::new(vec![
            RdPathSegment::TopLevel(8),
            RdPathSegment::Child(3),
            RdPathSegment::Option,
            RdPathSegment::Attribute("srcref".to_string()),
            RdPathSegment::AttributeValue,
            RdPathSegment::ListElement(2),
            RdPathSegment::CharacterElement(0),
        ]);
        assert_eq!(
            path.to_string(),
            "top-level[8] / child[3] / @option / @attr(srcref) / value / list[2] / character[0]"
        );
    }
}