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.
Exports
Section titled “Exports”url.escape_query
Section titled “url.escape_query”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"
url.unescape_query
Section titled “url.unescape_query”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")
url.escape_path_segment
Section titled “url.escape_path_segment”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"
url.unescape_path_segment
Section titled “url.unescape_path_segment”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
Section titled “struct Url”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.
Url.parse
Section titled “Url.parse”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()
Url.parse_request_uri
Section titled “Url.parse_request_uri”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()
Url.is_absolute
Section titled “Url.is_absolute”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")
Url.hostname
Section titled “Url.hostname”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"
Url.port
Section titled “Url.port”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
Url.escaped_path
Section titled “Url.escaped_path”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"
Url.escaped_fragment
Section titled “Url.escaped_fragment”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"
Url.request_uri
Section titled “Url.request_uri”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"
Url.redacted
Section titled “Url.redacted”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/"
Url.query_values
Section titled “Url.query_values”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"),
]
Url.with_query
Section titled “Url.with_query”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"
Url.resolve
Section titled “Url.resolve”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/"
Url.resolve_text
Section titled “Url.resolve_text”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"
Url.join_path
Section titled “Url.join_path”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"
Url.to_string
Section titled “Url.to_string”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"
Url.check
Section titled “Url.check”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)
Url.build
Section titled “Url.build”impl CheckedLiteral<Display, Url> for Url
fn build(fragments: List<Fragment<Display>>) -> Url
impl CheckedLiteral.build
Url.inspect
Section titled “Url.inspect”impl Debug for Url
fn inspect(value: Url) -> String
impl Debug.inspect
Url.equal
Section titled “Url.equal”impl Equatable for Url
fn equal(a: Url, b: Url) -> Bool
impl Equatable.equal
Url.hash
Section titled “Url.hash”impl Hashable for Url
fn hash(value: Url) -> Int
impl Hashable.hash
struct Userinfo
Section titled “struct Userinfo”struct Userinfo name: String password: Maybe<String> = None end
A URL’s user name and optional password.
Userinfo.to_string
Section titled “Userinfo.to_string”impl Display for Userinfo
fn to_string(user: Userinfo) -> String
impl Display.to_string
name or name:password, escaped as in a URL.
Userinfo.inspect
Section titled “Userinfo.inspect”impl Debug for Userinfo
fn inspect(value: Userinfo) -> String
impl Debug.inspect
Userinfo.equal
Section titled “Userinfo.equal”impl Equatable for Userinfo
fn equal(a: Userinfo, b: Userinfo) -> Bool
impl Equatable.equal
Userinfo.hash
Section titled “Userinfo.hash”impl Hashable for Userinfo
fn hash(value: Userinfo) -> Int
impl Hashable.hash
struct UrlError
Section titled “struct UrlError”struct UrlError url: String reason: String end
Why a URL or query could not be read: the text and the reason.
UrlError.to_string
Section titled “UrlError.to_string”impl Display for UrlError
fn to_string(error: UrlError) -> String
impl Display.to_string
UrlError.inspect
Section titled “UrlError.inspect”impl Debug for UrlError
fn inspect(value: UrlError) -> String
impl Debug.inspect
UrlError.equal
Section titled “UrlError.equal”impl Equatable for UrlError
fn equal(a: UrlError, b: UrlError) -> Bool
impl Equatable.equal
type Query
Section titled “type Query”type Query List<(String, String)>
A query string’s pairs, in order. A key may appear more than once.
Query.parse
Section titled “Query.parse”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()
Query.get
Section titled “Query.get”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
Query.values
Section titled “Query.values”fn values(query: Query, key: String) -> List<String>
type function on Query
Every value of key, in order.
Query.has
Section titled “Query.has”fn has(query: Query, key: String) -> Bool
type function on Query
Whether key has a value.
Query.set
Section titled “Query.set”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")]
Query.add
Section titled “Query.add”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.
Query.remove
Section titled “Query.remove”fn remove(query: Query, key: String) -> Query
type function on Query
The query without key.
Query.encode
Section titled “Query.encode”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"
Query.to_string
Section titled “Query.to_string”impl Display for Query
fn to_string(query: Query) -> String
impl Display.to_string
The query’s encoding, as Query.encode.
Query.inspect
Section titled “Query.inspect”impl Debug for Query
fn inspect(value: Query) -> String
impl Debug.inspect
Query.equal
Section titled “Query.equal”impl Equatable for Query
fn equal(a: Query, b: Query) -> Bool
impl Equatable.equal
Query.hash
Section titled “Query.hash”impl Hashable for Query
fn hash(value: Query) -> Int
impl Hashable.hash