Skip to content

std::url

URLs (RFC 3986): parsed into parts, built from literals, and percent-encoded. Parsing and writing follow Go’s net/url.

A Url is a parsed URL whose fields hold decoded text. Url.parse reads text and returns a UrlError for text that is not a URL, and Display writes the URL back escaped. A Url literal is checked when the program is checked, so a malformed one is a compile error, and it is a Url, not a Result, in every quote style:

api = Url"https://api.example.com/v1/"

users = Url.join_path(api, ["users", id])

search = Url.with_query(users, Query[("tab", "posts"), ("page", "2")])

In Url"...", each ${...} slot takes any Display value (a String, an Int, a Uuid, a type of your own) and escapes its text for where it stands, so data cannot change the URL’s shape: a slot in the path is one segment, one in the query is one key or value, and one after # is the fragment. A slot in the scheme, user or host is a compile error, since no escaping makes it safe there; build that URL with Url.parse.

profile = Url"https://example.com/users/${id}/posts?page=${page}"

A Query is a query string’s pairs, in order, and a key may appear more than once. Query.encode, and so Url.with_query, writes the pairs in that order.

For a piece of text rather than a whole URL, url.escape_query escapes a query key or value (a space as +), and url.escape_path_segment one segment of a path (a space as %20, and / escaped so it cannot start a new segment). Each unescape_ function reverses its escape_ function and returns an Err for a malformed % escape or text that is not UTF-8 once unescaped.

link = "/search/${url.escape_path_segment(tag)}?q=${url.escape_query(term)}"

Every function here is pure, so a typed literal’s handler may call them.

Import with import std::url.

fn escape_query(text: String) -> String

text percent-encoded as a query string’s key or value: letters, digits and -_.~ stay, a space becomes +, and every other byte of its UTF-8 is % and two uppercase hexadecimal digits.

import std::url

assert url.escape_query("tea & cake") == "tea+%26+cake"
assert url.escape_query("a/b?c=d") == "a%2Fb%3Fc%3Dd"
assert url.escape_query("café") == "caf%C3%A9"
fn unescape_query(text: String) -> Result<String, String>

The text a query string’s key or value holds: % escapes decoded, and + read as a space.

import std::url

assert url.unescape_query("tea+%26+cake") == Ok("tea & cake")
assert url.unescape_query("caf%C3%A9") == Ok("café")
assert url.unescape_query("100%") == Err("invalid percent escape \"%\"")
assert url.unescape_query("%FF") == Err("the unescaped text is not valid UTF-8")
fn escape_path_segment(text: String) -> String

text percent-encoded as one segment of a URL path: a space becomes %20, and / and ? are escaped so the text stays one segment.

import std::url

assert url.escape_path_segment("tea & cake") == "tea%20&%20cake"
assert url.escape_path_segment("a/b?c") == "a%2Fb%3Fc"
fn unescape_path_segment(text: String) -> Result<String, String>

The text a URL path segment holds: % escapes decoded, and + kept as itself.

import std::url

assert url.unescape_path_segment("tea%20&%20cake") == Ok("tea & cake")
assert url.unescape_path_segment("a+b") == Ok("a+b")
assert url.unescape_path_segment("%zz") == Err("invalid percent escape \"%zz\"")
struct Url
    scheme: String = ""
    user: Maybe<Userinfo> = None
    host: String = ""
    path: String = ""
    raw_path: Maybe<String> = None
    query: Maybe<String> = None
    fragment: Maybe<String> = None
    raw_fragment: Maybe<String> = None
    opaque_part: Maybe<String> = None
    omit_host: Bool = False
end

A parsed URL: scheme://user:password@host/path?query#fragment. The fields hold decoded text, and Display writes the URL back escaped.

fn parse(text: String) -> Result<Url, UrlError>

type function on Url

text read as a URL, absolute or relative, as Go’s url.Parse reads it.

import std::url.Url

u = Url.parse("https://ann:pw@example.com:8080/a%20b?q=1#top")!
assert u.scheme == "https"
assert u.host == "example.com:8080"
assert u.path == "/a b"
assert u.query == Some("q=1")
assert u.fragment == Some("top")
assert Maybe.map(u.user, fn user -> user.name) == Some("ann")
assert Url.parse("http://[::1]:namedport") |> Result.is_err()
fn parse_request_uri(text: String) -> Result<Url, UrlError>

type function on Url

text read as the target of an HTTP request: an absolute URL or an absolute path, with no fragment. Go’s url.ParseRequestURI.

import std::url.Url

assert Url.parse_request_uri("/users?id=7")!.path == "/users"
assert Url.parse_request_uri("users") |> Result.is_err()
fn is_absolute(url: Url) -> Bool

type function on Url

Whether the URL has a scheme.

import std::url.Url

assert Url.is_absolute(Url"https://example.com")
assert not Url.is_absolute(Url"/a/b")
fn hostname(url: Url) -> String

type function on Url

The host without its port, and without the brackets of an IPv6 address.

import std::url.Url

assert Url.hostname(Url"http://[::1]:8080/") == "::1"
fn port(url: Url) -> Maybe<String>

type function on Url

The host’s port, if it names one.

import std::url.Url

assert Url.port(Url"http://example.com:8080") == Some("8080")
assert Url.port(Url"http://example.com") == None
fn escaped_path(url: Url) -> String

type function on Url

The path as it is written in the URL: raw_path when it is set, else path escaped.

import std::url.Url

assert Url.escaped_path(Url"https://example.com/a b") == "/a%20b"
fn escaped_fragment(url: Url) -> String

type function on Url

The fragment as it is written in the URL.

import std::url.Url

assert Url.escaped_fragment(Url"https://example.com/#a b") == "a%20b"
fn request_uri(url: Url) -> String

type function on Url

The target an HTTP request line carries: the escaped path and the query, or the opaque part.

import std::url.Url

assert Url.request_uri(Url"https://example.com/a b?q=1#top") == "/a%20b?q=1"
fn redacted(url: Url) -> String

type function on Url

The URL written with its password, if any, replaced by xxxxx.

import std::url.Url

assert Url.redacted(Url"https://ann:secret@example.com/") == "https://ann:xxxxx@example.com/"
fn query_values(url: Url) -> Query

type function on Url

The URL’s query read into pairs. A pair Go cannot read is left out; Query.parse reports it instead.

import std::url.{Query, Url}

assert Url.query_values(Url"https://example.com/?a=1&b=2&a=3") == Query[
    ("a", "1"),
    ("b", "2"),
    ("a", "3"),
]
fn with_query(url: Url, query: Query) -> Url

type function on Url

The URL with its query replaced by query, encoded as Query.encode writes it, the pairs in their order.

import std::url.{Query, Url}

u = Url.with_query(Url"https://example.com/s", Query[("q", "tea & cake"), ("n", "2")])
assert "${u}" == "https://example.com/s?q=tea+%26+cake&n=2"
fn resolve(base: Url, reference: Url) -> Url

type function on Url

reference resolved against base, as RFC 3986 section 5.2 does: how a browser follows a link.

import std::url.Url

base = Url"https://example.com/a/b/c"
assert "${Url.resolve(base, Url"../d?x=1")}" == "https://example.com/a/d?x=1"
assert "${Url.resolve(base, Url"//other.org/")}" == "https://other.org/"
fn resolve_text(base: Url, reference: String) -> Result<Url, UrlError>

type function on Url

reference parsed and resolved against base.

import std::url.Url

assert "${Url.resolve_text(Url"https://example.com/a/", "b")!}" == "https://example.com/a/b"
fn join_path(url: Url, segments: List<String>) -> Url

type function on Url

The URL with segments joined to its path, as Go’s JoinPath joins them, and . and .. cleaned from the result. A / in a segment separates segments; escape one with url.escape_path_segment to keep it whole.

import std::url.Url

u = Url.join_path(Url"https://example.com/api/", ["users", "7", "../8"])
assert "${u}" == "https://example.com/api/users/8"

impl Display for Url

fn to_string(url: Url) -> String

impl Display.to_string

The URL written back, escaped as Go’s URL.String writes it.

import std::url.Url

assert "${Url.parse("https://example.com/a b?q=1#x y")!}" == "https://example.com/a%20b?q=1#x%20y"

impl CheckedLiteral<Display, Url> for Url

fn check(statics: List<String>) -> Result<Unit, LiteralError>

impl CheckedLiteral.check

A Url literal is a Url in every quote style, never a Result, and is checked when the program is checked: text that Url.parse would refuse is a compile error. Url"https://example.com/a" is the URL Url.parse reads from its text. In Url"...", a ${...} slot takes any Display value, and its text is escaped for where it stands: as one path segment in the path, as a key or value in the query, and as the fragment after #. A slot of . or .. in the path is escaped too, so it cannot climb the path. A slot in the scheme, user or host is a compile error whatever its type, since no escaping makes it safe there; build such a URL with Url.parse.

A Query or a Url in a slot is its text, escaped like any other: ?q=${query} is one value, not the query’s pairs, and /${url} one segment. Add pairs with Url.with_query and segments with Url.join_path.

import std::url.{Query, Url}
import std::uuid.Uuid
import std::display.Display
import std::literals::testing.build_each

id = "a/b c"
tab = "x&y"
u = Url"https://example.com/users/${id}?tab=${tab}#${tab}"
assert u.path == "/users/a/b c"
assert "${u}" == "https://example.com/users/a%2Fb%20c?tab=x%26y#x&y"

// A slot takes any Display value: its text is escaped as a String's.
user = Uuid.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")!
page = 2
p = Url"/admin/users/${user}/edit?page=${page}#${page}"
assert "${p}" == "/admin/users/6ba7b810-9dad-11d1-80b4-00c04fd430c8/edit?page=2#2"

// A Query or a Url is its text too, one segment or one value.
q = Query[("a", "1"), ("b", "x y")]
s = Url"/s/${q}?q=${q}"
assert "${s}" == "/s/a=1&b=x+y?q=a%3D1%26b%3Dx%2By"
home = Url"https://example.com/"
g = Url"/go/${home}"
assert "${g}" == "/go/https:%2F%2Fexample.com%2F"

// An empty slot is an empty segment, and cannot make a relative
// URL name a host: `//b` would be the host `b`.
empty = ""
r = Url"/${empty}/b"
assert r.host == ""
assert "${r}" == "/.//b"

// A slot of `.` or `..` is written escaped, so data cannot climb the
// path with a dot segment.
up = ".."
f = Url"/files/${up}/secret"
assert "${f}" == "/files/%2E%2E/secret"

// check accepts these statics, so build takes every value.
statics = ["https://example.com/users/", "?tab=", ""]

assert Ok(urls) = build_each<Display, Url>(
    statics,
    ["", "..", "a/b c", 7, user],
    Url.check,
    Url.build,
)

assert Iter.all_match(urls, fn v -> v.host == "example.com")
assert Err(_) = build_each<Display, Url>(["https://", "/"], ["x"], Url.check, Url.build)

impl CheckedLiteral<Display, Url> for Url

fn build(fragments: List<Fragment<Display>>) -> Url

impl CheckedLiteral.build

impl Debug for Url

fn inspect(value: Url) -> String

impl Debug.inspect

impl Equatable for Url

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

impl Equatable.equal

impl Hashable for Url

fn hash(value: Url) -> Int

impl Hashable.hash

struct Userinfo
    name: String
    password: Maybe<String> = None
end

A URL’s user name and optional password.

impl Display for Userinfo

fn to_string(user: Userinfo) -> String

impl Display.to_string

name or name:password, escaped as in a URL.

impl Debug for Userinfo

fn inspect(value: Userinfo) -> String

impl Debug.inspect

impl Equatable for Userinfo

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

impl Equatable.equal

impl Hashable for Userinfo

fn hash(value: Userinfo) -> Int

impl Hashable.hash

struct UrlError
    url: String
    reason: String
end

Why a URL or query could not be read: the text and the reason.

impl Display for UrlError

fn to_string(error: UrlError) -> String

impl Display.to_string

impl Debug for UrlError

fn inspect(value: UrlError) -> String

impl Debug.inspect

impl Equatable for UrlError

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

impl Equatable.equal

type Query List<(String, String)>

A query string’s pairs, in order. A key may appear more than once.

fn parse(text: String) -> Result<Query, UrlError>

type function on Query

text, a query string without its ?, read into pairs in order. Each key and value is unescaped, + read as a space. A ; or a bad escape is an Err.

import std::url.Query

assert Query.parse("q=tea+cake&n=2")! == Query[("q", "tea cake"), ("n", "2")]
assert Query.parse("a=1;b=2") |> Result.is_err()
fn get(query: Query, key: String) -> Maybe<String>

type function on Query

The first value of key.

import std::url.Query

assert Query.get(Query[("a", "1"), ("a", "2")], "a") == Some("1")
assert Query.get(Query[], "a") == None
fn values(query: Query, key: String) -> List<String>

type function on Query

Every value of key, in order.

fn has(query: Query, key: String) -> Bool

type function on Query

Whether key has a value.

fn set(query: Query, key: String, value: String) -> Query

type function on Query

The query with key’s values replaced by value, in the place of its first value, or added at the end.

import std::url.Query

q = Query[("a", "1"), ("b", "2"), ("a", "3")]
assert Query.set(q, "a", "9") == Query[("a", "9"), ("b", "2")]
assert Query.set(q, "c", "4") == Query[("a", "1"), ("b", "2"), ("a", "3"), ("c", "4")]
fn add(query: Query, key: String, value: String) -> Query

type function on Query

The query with value added to key’s values, at the end.

fn remove(query: Query, key: String) -> Query

type function on Query

The query without key.

fn encode(query: Query) -> String

type function on Query

The query encoded: each pair as key=value, both escaped as url.escape_query does, in the pairs’ order and joined with &.

import std::url.Query

assert Query.encode(Query[("b", "x y"), ("a", "1"), ("b", "&")]) == "b=x+y&a=1&b=%26"

impl Display for Query

fn to_string(query: Query) -> String

impl Display.to_string

The query’s encoding, as Query.encode.

impl Debug for Query

fn inspect(value: Query) -> String

impl Debug.inspect

impl Equatable for Query

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

impl Equatable.equal

impl Hashable for Query

fn hash(value: Query) -> Int

impl Hashable.hash