supertext 0.0.4

html document tools
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

# supertext

hypertext, a bit less hyper

i want to construct HTML documents in some Rust code. i don't want a full
templating solution. i just want to append some tags and not forget to escape
user-provided input.

you probably don't want to use this, but if you do it should work. public
interfaces are basically expected to break. it is 0.0.1 for a reason.

## example

```rust
pub fn example(items: &[(String, String)]) -> Result<String, std::fmt::Error> {
    let mut out = String::new();
    let mut writer = HtmlWriter::new(&mut out);

    let mut html = HtmlSink::root(&mut writer);

    {
        let mut style = html.open_tag(style());
        style.rule(".table { font-family: monospace; border: 1px solid black; }")?;
        style.rule(".row-item { padding-left: 4px; padding-right: 4px; border-right: 1px solid black; }")?;
        style.rule(".odd-row { background: #eee; }")?;
        style.rule(".even-row { background: #ddd; }")?;
    }

    {
        let mut header = html.open_tag(h1());
        header.text("an example page that is super cool")?;
    }

    {
        let mut description = html.open_tag(p());
        match items.len() {
            0 => description.text("no items")?,
            1 => description.text("one item")?,
            o => description.text(&format!("{} items", o))?,
        };
    }

    let mut table = html.open_tag(table().class("table"));
    {
        let mut header = table.header();
        let th = th().class("row-item");
        let mut add_cell = |name: &'static str| header.open_tag(th.clone()).text(name);
        add_cell("key")?;
        add_cell("value")?;
    }

    let td = td().class("row-item");

    for (i, item) in items.iter().enumerate() {
        let mut row = table.row(tr().class(["even-row", "odd-row"][i % 2]));

        {
            let mut elem = row.open_tag(td.clone());
            elem.open_tag(a().href(&format!("/{}", item.0))).text(&item.0)?;
        }
        {
            row.open_tag(td.clone()).text(&item.1)?;
        }
    }

    table.close();

    html.close();

    Ok(out)
}
```

## non-goals

this crate is intended to avoid trivially injectable HTML document
construction. it is not intended to prevent semantically incoherent HTML
documents. yet?

for example, this crate allows creating a table with twelve columns in its
header, but varying (and not-twelve) rows afterwards. this crate allows
tags to reference styles that are undefined. this crate allows intra-page
links that are invalid. this crate allows syntactically invalid CSS.

## TODO

- [ ] element nesting could be more principled: sections like `phrasing content`
      in the HTML spec draw a clearer line about what elements can be nested.
- [ ] really want to fuzz document construction and ensure no inputs produce
      different trees when parsed than when constructed
- [ ] really want to be able to check if strings need escaping at compile time
      rather than runtime
- [ ] for strings that need runtime escaping, would really like to not reallocate
      for replaced strings - retaining borrows of original data and not
      producing interim replaced copies would be nice. maybe something like a
      rope instead? or views on the underlying string with buffers of
      replacements to be evaluated when rendered out.
- [ ] what to do with css rules? each rule gets a newline currently, is that ok?
- [ ] controlling indentation for paragraphs? `p.text()` lines always just
      appends escaped text to the writer, maybe those should be spaced with
      newlines? should `text()` automatically append a line break?

## related work (and things this is not)

[build\_html](https://docs.rs/build_html/latest/build_html/) looks good,
almost is what i want! unfortunately: 

> Note that escaping strings is also not automatic. You should use the
> escape\_html function if you are displaying untrusted text.

the API was already wanted more ceremony than i was happy with, but this moves
it out of the running.

[html](https://docs.rs/html/latest/html/) is comprehensive, but perhaps too
much so.

the docs surface area is roughly the product of all kinds of tags by all kinds
of tags, to the point i have a bit of a difficult time with navigation. it
includes lots of HTML spec that is probably interesting and meaningful if
i was doing interesting things with HTML, but i'm not.

needing to set `#![recursion_limit = "512"]` when depending on this crate is
another papercut; between that and its idleness, i'm OK passing here.

[maud](https://docs.rs/maud/latest/maud/) ([book](https://maud.lambda.xyz/))
seems good, but i don't want a template engine, i just want to put a few divs
and spans together. more importantly, i want to be able to render elements of
a page potentially independently. having to construct an entire HTML document
in one go is not great, and having to learn a new syntax for control flow in
the document is the opposite direction of what i want.