Skip to content

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 ! UrlErrortext, relative to base when given; UrlError { message } for text that isn't a URL
canParse(text: string, base?: string): booleanwhether it parses
update(url: Url, changes: UrlChanges): Urlthe 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 ! UrlErrora 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][]): Urlits 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 %XX a 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 of name.
  • 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 ! UrlErrorJS's encodeURIComponent: all but letters, digits and -_.!~*'() as UTF-8 %XX
decodeComponent(text: string): string ! UrlErrorJS's decodeURIComponent
encode(text: string): string ! UrlErrorJS's encodeURI: also keeps the reserved ;/?:@&=+$,#
decode(text: string): string ! UrlErrorJS'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.

Weft is in development. The reference is the spec as it stands today.