Skip to content

std::html

HTML for a server to send: one value type, Html, written as an Html"..." or Html"""...""" literal that the compiler reads as an HTML template when it checks the program (spec §18 HTML templates).

import std::html.Html

fn badge(count: Int) -> Html
    Html"<span class='badge'>${count}</span>"
end

fn comment(author: String, body: String) -> Html
    Html"""
    <article class="comment">
      <p class="author">${author}</p>
      <p>${body}</p>
    </article>
    """
end

Each ${...} is written by where it stands. In element text an Html is inserted as it is, a ToHtml value renders itself, and a String or any other Display value is escaped as text; a quoted attribute value takes any Display; the start of an href or src takes a Url or a SafeUrl; later in a URL a value is escaped for the path segment, query value or fragment it stands in, so /p/${id} writes a / in id as %2F; a style value takes a number or a Css; checked=${on} takes a Bool or a Maybe<String> and writes the attribute or leaves it out. Everywhere else a Maybe writes its value, or nothing for None, so an if adds a class when its condition holds: class='badge ${if on then Some("on") else None}'. A slot where no escaping is safe, markup that is not closed, and a value with no rendering where it stands are compile errors.

Html.each renders a list, and Html.concat joins parts:

fn names(all: List<String>) -> Html
    Html"<ul>${Html.each(all, fn name -> Html"<li>${name}</li>")}</ul>"
end

An attribute value may be quoted with " or '. A one-line fragment is usually written Html"..." with ' around its attributes, and markup of several lines Html"""...""".

Html.trusted inserts markup as written, unescaped: for HTML a trusted renderer produced, such as Markdown, and never for text a user wrote.

Import with import std::html.

struct Html

opaque — construction surface is private to its defining module

Rendered HTML: balanced markup from templates, or markup a program vouches for through Html.trusted. Two Html values are equal when they render the same text.

assert Html.to_string(Html"<b>${"<i>"}</b>") == "<b>&lt;i&gt;</b>"

// A `Maybe` in a quoted attribute value writes its value, or nothing.
tag = fn on: Bool -> Html"<b class='tag ${if on then Some("on") else None}'></b>"
assert Html.to_string(tag(True)) == "<b class='tag on'></b>"
assert Html.to_string(tag(False)) == "<b class='tag '></b>"

count: Maybe<Int> = None
assert Html.to_string(Html"<b data-count='${count}'></b>") == "<b data-count=''></b>"

impl Debug for Html

fn inspect(html: Html) -> String

impl Debug.inspect

The rendered text, as Html("<p>hi</p>").

assert Debug.inspect(Html"<p>hi</p>") == "Html(\"<p>hi</p>\")"
fn trusted(markup: String) -> Html

type function on Html

Markup inserted as written, unescaped: for HTML a trusted renderer produced, such as Markdown. Never for text from a user, which Html.text or a template’s slot escapes.

assert Html.to_string(Html.trusted("<em>x</em>")) == "<em>x</em>"
fn text(value: String) -> Html

type function on Html

Text, escaped.

assert Html.to_string(Html.text("a < b & c")) == "a &lt; b & c"
fn empty() -> Html

type function on Html

No markup.

assert Html.to_string(Html.empty()) == ""
fn concat(parts: List<Html>) -> Html

type function on Html

The parts, in order.

assert Html.to_string(Html.concat([Html"<b>1</b>", Html"<b>2</b>"])) == "<b>1</b><b>2</b>"
fn each<T>(items: List<T>, item: (T) -> Html) -> Html

type function on Html

The markup item makes of each of items, in order.

items = Html.each([1, 2], fn n -> Html"<li>${n}</li>")
assert Html.to_string(items) == "<li>1</li><li>2</li>"
fn to_string(html: Html) -> String

type function on Html

The markup as text.

name = "Bo & Co"
assert Html.to_string(Html"<p>${name}</p>") == "<p>Bo & Co</p>"
fn write_to(html: Html, writer: Writer) -> Result<Unit, Error>

type function on Html

Writes the markup to writer.

import std::io

ran = io.capture("", fn -> Html.write_to(Html"<p>hi</p>", io.stdout))
assert ran.value == Result.Ok(Unit)
assert ran.output == "<p>hi</p>"

impl ToHtml for Html

fn to_html(value: Html) -> Html

impl ToHtml.to_html

impl Equatable for Html

fn equal(a: Html, b: Html) -> Bool

impl Equatable.equal

interface ToHtml
    fn to_html(value: self) -> Html
end

A value that renders itself in an element’s content: String and the numbers as escaped text, an Html as it is, a List<Html> joined, and a Maybe of any of them as its value, or nothing for None, so if shown then Some(part) else None shows the part or nothing. Element content writes a Display value that is not a ToHtml as escaped text; a program’s own type implements ToHtml to render as markup instead.

parts = [Html"<i>a</i>", Html"<i>b</i>"]
assert Html.to_string(Html"<p>${"a < b"} ${2} ${parts}</p>") == "<p>a &lt; b 2 <i>a</i><i>b</i></p>"
fn to_html(value: self) -> Html

interface ToHtml

interface UrlValue
    fn to_url(value: self) -> String
end

A value a URL attribute’s value can start with: a Url, whose scheme must be http, https, mailto or tel (another is written as about:invalid#unsafe-url), or a SafeUrl, which the program vouches for. A relative Url has no scheme and is written as it is.

link = fn text: String -> Html"<a href='${Url.parse(text) |> Result.to_maybe()}'>x</a>"

assert Html.to_string(link("/about")) == "<a href='/about'>x</a>"
assert Html.to_string(link("javascript:alert(1)")) == "<a href='about:invalid#unsafe-url'>x</a>"
fn to_url(value: self) -> String

interface UrlValue

type SafeUrl String

A URL the program vouches for, whatever its scheme: written as it is, escaped for the attribute.

data = SafeUrl("data:text/plain,a&b")
assert Html.to_string(Html"<a href='${data}'>x</a>") == "<a href='data:text/plain,a&b'>x</a>"

impl UrlValue for SafeUrl

fn to_url(SafeUrl(value)) -> String

impl UrlValue.to_url

impl Debug for SafeUrl

fn inspect(value: SafeUrl) -> String

impl Debug.inspect

interface CssValue
    fn to_css(value: self) -> String
end

A value a style attribute can hold: a number, or a Css the program vouches for.

fn to_css(value: self) -> String

interface CssValue

type Css String

CSS the program vouches for, escaped for the attribute.

bar = Html"<i style='color: ${Css("red")}; width: ${40}%'></i>"
assert Html.to_string(bar) == "<i style='color: red; width: 40%'></i>"

impl CssValue for Css

fn to_css(Css(value)) -> String

impl CssValue.to_css

impl Debug for Css

fn inspect(value: Css) -> String

impl Debug.inspect

interface OptionalAttribute
    fn attribute(value: self) -> Maybe<String>
end

An attribute written or left out by its value, in name=${value}: True writes the bare attribute and False leaves it out; Some(text) writes name="text", escaped, and None leaves it out.

box = fn on: Bool, tip: Maybe<String> -> Html"<input checked=${on} title=${tip}>"

assert Html.to_string(box(True, Some("a & b"))) == "<input checked title=\"a & b\">"
assert Html.to_string(box(False, None)) == "<input>"
fn attribute(value: self) -> Maybe<String>

interface OptionalAttribute

The attribute’s value, Some("") for a bare attribute, or None to leave it out.