auk 0.6.0

An eDSL for writing HTML using standard Rust syntax.
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
139
140
141
142
143
144
145
146
147
148
149
150

//! Constructs for traversing and manipulating trees of [`HtmlElement`]s.

use crate::{Element, HtmlElement, TextElement};

/// A visitor for [`HtmlElement`]s.
pub trait Visitor: Sized {
    /// The type of error this visitor returns.
    type Error;

    /// Visits the given [`HtmlElement`].
    fn visit(&mut self, element: &HtmlElement) -> Result<(), Self::Error> {
        walk_element(self, element)
    }

    /// Visits the given text.
    fn visit_text(&mut self, _text: &str) -> Result<(), Self::Error> {
        Ok(())
    }

    /// Visits the given attribute.
    fn visit_attr(&mut self, _name: &str, _value: &str) -> Result<(), Self::Error> {
        Ok(())
    }

    /// Visits the children of an [`HtmlElement`].
    fn visit_children(&mut self, children: &[Element]) -> Result<(), Self::Error> {
        walk_children(self, children)
    }
}

/// Walks the given [`HtmlElement`].
pub fn walk_element<V: Visitor>(visitor: &mut V, element: &HtmlElement) -> Result<(), V::Error> {
    for (name, value) in &element.attrs {
        visitor.visit_attr(name, value)?;
    }

    visitor.visit_children(&element.children)?;

    Ok(())
}

/// Walks the given children.
pub fn walk_children<V: Visitor>(visitor: &mut V, children: &[Element]) -> Result<(), V::Error> {
    for child in children {
        match child {
            Element::Html(element) => visitor.visit(element)?,
            Element::Text(TextElement { text }) => visitor.visit_text(text)?,
        }
    }

    Ok(())
}

/// A mutating visitor for [`HtmlElement`]s.
pub trait MutVisitor: Sized {
    /// The type of error this visitor returns.
    type Error;

    /// Visits the given [`HtmlElement`].
    fn visit(&mut self, element: &mut HtmlElement) -> Result<(), Self::Error> {
        noop_visit_element(self, element)
    }

    /// Visits the given text.
    fn visit_text(&mut self, _text: &mut String) -> Result<(), Self::Error> {
        Ok(())
    }

    /// Visits the given attribute.
    fn visit_attr(&mut self, _name: &str, _value: &mut String) -> Result<(), Self::Error> {
        Ok(())
    }

    /// Visit the children of an [`HtmlElement`].
    fn visit_children(&mut self, children: &mut [Element]) -> Result<(), Self::Error> {
        noop_visit_children(self, children)
    }
}

/// Walks the given [`HtmlElement`] without mutating it.
pub fn noop_visit_element<V: MutVisitor>(
    visitor: &mut V,
    element: &mut HtmlElement,
) -> Result<(), V::Error> {
    for (name, value) in &mut element.attrs {
        visitor.visit_attr(name, value)?;
    }

    visitor.visit_children(&mut element.children)?;

    Ok(())
}

/// Walks the given children without mutating it..
pub fn noop_visit_children<V: MutVisitor>(
    visitor: &mut V,
    children: &mut [Element],
) -> Result<(), V::Error> {
    for child in children {
        match child {
            Element::Html(element) => visitor.visit(element)?,
            Element::Text(TextElement { text }) => visitor.visit_text(text)?,
        }
    }

    Ok(())
}

#[cfg(test)]
mod tests {
    use insta::assert_yaml_snapshot;

    use crate::renderer::HtmlElementRenderer;
    use crate::*;

    use super::*;

    #[test]
    fn test_mut_visitor_attribute_replacement() {
        struct ReplaceAttr;

        impl MutVisitor for ReplaceAttr {
            type Error = ();

            fn visit_attr(&mut self, name: &str, value: &mut String) -> Result<(), Self::Error> {
                if name == "href" {
                    *value = format!("https://example.com/{value}");
                }

                Ok(())
            }
        }

        let mut element = html().child(head().child(title())).child(
            body().child(
                ul().child(li().child(a().href("home")))
                    .child(li().child(a().href("features")))
                    .child(li().child(a().href("about"))),
            ),
        );

        let mut visitor = ReplaceAttr;

        visitor.visit(&mut element).unwrap();

        assert_yaml_snapshot!(HtmlElementRenderer::new()
            .render_to_string(&element)
            .unwrap());
    }
}