/// Server-rendered HTML.
///
/// Inline literals such as `
{name}
` build `Element`s;
/// `render` turns them into HTML text, escaping text and attribute values.
/// See docs/adr/0009-html-literals.md for the typing rules.
import std/bytes
/// An HTML tree. `msg` is the type of messages event handlers send on the
/// client target (after v0); server-rendered pages use `Html`.
pub type Element
{ Node(tag: String, attributes: List, children: List>)
, Text(String)
, Raw(String)
, Fragment(List>)
}
/// `name="value"`, a boolean attribute present when `True`, or an
/// optional value (`None` leaves the attribute out).
pub type Attribute
{ Attribute(String, String)
, Flag(String, Bool)
, Optional(String, Option)
}
pub type Html = Element
/// Text, escaped when rendered.
pub fn text :: value: String -> Element
{
Text(value)
}
/// Markup inserted without escaping. Only for trusted HTML.
pub fn raw :: markup: String -> Element
{
Raw(markup)
}
pub fn render :: element: Element -> String
{
bytes.build_string (render_into element (bytes.builder ()))
}
// Everything is appended into one builder, which stays unique the whole
// way: appends are in place (amortized), escaping writes straight into
// the buffer, and `build_string` hands the buffer over without copying.
fn render_into :: element b
{
match element
{ Text(t) -> append_escaped b t
, Raw(markup) -> bytes.append_string b markup
, Fragment(children) -> render_all children b
, Node(tag, attributes, children) ->
{
let opened =
render_attributes
attributes
(b |> bytes.append_string "<" |> bytes.append_string tag)
|> bytes.append_string ">"
if is_void tag
{
opened
}
else
{
render_all children opened
|> bytes.append_string ""
|> bytes.append_string tag
|> bytes.append_string ">"
}
}
}
}
fn render_all :: children b
{
match children
{ [] -> b, [child, ..rest] -> render_all rest (render_into child b) }
}
fn render_attributes :: attributes b
{
match attributes
{ [] -> b
, [Attribute(name, value), ..rest] ->
render_attributes
rest
( b
|> bytes.append_string " "
|> bytes.append_string name
|> bytes.append_string "=\""
|> append_escaped value
|> bytes.append_string "\""
)
, [ Flag(name, on)
, ..rest
] -> if on
{
render_attributes
rest
(b |> bytes.append_string " " |> bytes.append_string name)
}
else
{
render_attributes rest b
}
, [Optional(name, value), ..rest] -> match value
{ Some(v) ->
render_attributes
rest
( b
|> bytes.append_string " "
|> bytes.append_string name
|> bytes.append_string "=\""
|> append_escaped v
|> bytes.append_string "\""
)
, None -> render_attributes rest b
}
}
}
/// Elements that never have content or a closing tag.
fn is_void :: tag
{
match tag
{ "area"
| "base"
| "br"
| "col"
| "embed"
| "hr"
| "img"
| "input"
| "link"
| "meta"
| "source"
| "track"
| "wbr" -> True
, _ -> False
}
}
/// Escape `& < > " '` for text and attribute values. A string without
/// metacharacters is returned as is.
@extern c "tl_html_escape" owned
pub fn escape :: s: String -> String
/// `b` with `s` appended, escaped: the escaped form is written straight
/// into the buffer, without an intermediate string.
@extern c "tl_bytes_append_escaped" owned
fn append_escaped :: b: bytes.Builder s: String -> bytes.Builder