Appearance
std/url
From the spec
This page is spec/std/url.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).
URLs as the WHATWG URL Standard parses them (what JS's URL does), query strings by URLSearchParams's rules, percent-encoding as encodeURIComponent and its siblings, and base64url. It is written in Weft (core/crates/weft-check/src/std/url.weft) over std/$url, which only parses URLs and sets their parts: on the VM the url crate, on the JS backend the engine's URL, both WHATWG. Everything else is this module's own code on both. User code (std/sandbox) may import it.
weft
import { parse, build, query, queryValue, encodeComponent } from "std/url"
let u = try parse("https://example.com:8443/search?q=a+b&lang=sl#top")
u.hostname // "example.com"
queryValue(u.search, "q") // "a b"
(try build({ protocol: "https", host: "api.example.com", pathname: "/v1/items", query: [["page", "2"]] })).href
// "https://api.example.com/v1/items?page=2"
`https://example.com/u/${try encodeComponent("anna smith")}` // ".../u/anna%20smith"URLs
Url | { href, protocol, username, password, host, hostname, port, pathname, search, hash, origin }, all strings, as JS's URL gives them: protocol ends in :, search starts with ? and hash with # (each "" when empty), port is "" for the scheme's default, host is hostname and the port, origin is "null" for schemes without one. Hosts are as the standard writes them: lowercase, IDNA (bücher.example → xn--bcher-kva.example), IPv6 in brackets. Data |
parse(text: string, base?: string): Url ! UrlError | text, relative to base when given; UrlError { message } for text that isn't a URL |
canParse(text: string, base?: string): boolean | whether it parses |
update(url: Url, changes: UrlChanges): Url | the parts changes gives set (protocol, username, password, host, hostname, port, pathname, search, hash, in that order), each as URL's setter does: a value the part can't take leaves it as it was |
build(parts: UrlParts): Url ! UrlError | a URL from protocol (with or without :), host and optionally username, password, port, pathname, query (pairs, form-encoded) and hash. Fails with UrlError when protocol and host don't make one |
params(url: Url): [string, string][] | its query's pairs (query(url.search)) |
withQuery(url: Url, pairs: [string, string][]): Url | its query replaced (no pairs: no ?) |
Query strings
application/x-www-form-urlencoded, as URLSearchParams:
query(text: string): [string, string][]: the pairs in order (a leading?skipped;&-separated, empty pieces skipped; the name up to the first=, the value after it or"").+is a space and%XXa byte; a malformed escape stays as written, and bytes that aren't UTF-8 become U+FFFD.queryValue(text: string, name: string): string?: the first value ofname.formatQuery(pairs: [string, string][]): string: without the?: letters, digits and*-._as they are, a space as+, everything else as UTF-8%XX(uppercase).
Percent-encoding
encodeComponent(text: string): string ! UrlError | JS's encodeURIComponent: all but letters, digits and -_.!~*'() as UTF-8 %XX |
decodeComponent(text: string): string ! UrlError | JS's decodeURIComponent |
encode(text: string): string ! UrlError | JS's encodeURI: also keeps the reserved ;/?:@&=+$,# |
decode(text: string): string ! UrlError | JS's decodeURI: an escape of a reserved character stays as written |
Where JS throws URIError these fail with UrlError: a lone surrogate to encode; an escape that isn't % and two hex digits, or escapes that aren't UTF-8 (overlong, surrogates, past U+10FFFF, cut short), to decode.
base64url
base64url.encode(b: Bytes): string (RFC 4648 §5, unpadded) and base64url.decode(text: string): Bytes ! UrlError (with or without padding; UrlError for other characters or a last character with bits past the data). b.toBase64() is the standard alphabet.
std/$url
parse(text, base): the eleven parts in Url's order, or null; set(href, part, value): the parts after one setter.