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.
Exports
Section titled “Exports”struct Html
Section titled “struct 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><i></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>"
Html.inspect
Section titled “Html.inspect”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>\")"
Html.trusted
Section titled “Html.trusted”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>"
Html.text
Section titled “Html.text”fn text(value: String) -> Html
type function on Html
Text, escaped.
assert Html.to_string(Html.text("a < b & c")) == "a < b & c"
Html.empty
Section titled “Html.empty”fn empty() -> Html
type function on Html
No markup.
assert Html.to_string(Html.empty()) == ""
Html.concat
Section titled “Html.concat”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>"
Html.each
Section titled “Html.each”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>"
Html.to_string
Section titled “Html.to_string”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>"
Html.write_to
Section titled “Html.write_to”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>"
Html.to_html
Section titled “Html.to_html”impl ToHtml for Html
fn to_html(value: Html) -> Html
impl ToHtml.to_html
Html.equal
Section titled “Html.equal”impl Equatable for Html
fn equal(a: Html, b: Html) -> Bool
impl Equatable.equal
interface ToHtml
Section titled “interface ToHtml”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 < b 2 <i>a</i><i>b</i></p>"
ToHtml.to_html
Section titled “ToHtml.to_html”fn to_html(value: self) -> Html
interface ToHtml
interface UrlValue
Section titled “interface UrlValue”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>"
UrlValue.to_url
Section titled “UrlValue.to_url”fn to_url(value: self) -> String
interface UrlValue
type SafeUrl
Section titled “type SafeUrl”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>"
SafeUrl.to_url
Section titled “SafeUrl.to_url”impl UrlValue for SafeUrl
fn to_url(SafeUrl(value)) -> String
impl UrlValue.to_url
SafeUrl.inspect
Section titled “SafeUrl.inspect”impl Debug for SafeUrl
fn inspect(value: SafeUrl) -> String
impl Debug.inspect
interface CssValue
Section titled “interface CssValue”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.
CssValue.to_css
Section titled “CssValue.to_css”fn to_css(value: self) -> String
interface CssValue
type Css
Section titled “type Css”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>"
Css.to_css
Section titled “Css.to_css”impl CssValue for Css
fn to_css(Css(value)) -> String
impl CssValue.to_css
Css.inspect
Section titled “Css.inspect”impl Debug for Css
fn inspect(value: Css) -> String
impl Debug.inspect
interface OptionalAttribute
Section titled “interface OptionalAttribute”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>"
OptionalAttribute.attribute
Section titled “OptionalAttribute.attribute”fn attribute(value: self) -> Maybe<String>
interface OptionalAttribute
The attribute’s value, Some("") for a bare attribute, or None to
leave it out.