Module url/index

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

Parse a URL string into a Url (D13 — a pure transform returns a Result; parse_exn is the effect-carrying wrapper).

Supports scheme://[userinfo@]host[:port]/path[?query][#fragment] and opaque scheme:path URIs like mailto:user@example.com.

parse as an effect: throws the UrlError through exn instead of returning it. Kept for callers already inside an effect scope.

.None for a relative reference — which is what makes §5.3's first branch ("the reference is already absolute") testable.

The host, still percent-encoded, with an IPv6 literal keeping its brackets ([::1]) — Rust's Url::host_str.

.None means "no host to speak of", which covers TWO different URLs: an opaque URI with no // authority at all (mailto:a@b), and an authority whose host is empty (file:///a/b). This library does not distinguish them, which is a divergence from Rust — see the module doc's ## Stability note.

The port as written, or .None when the URL carried no :port.

.None is NOT "the scheme's default port": nothing here knows that http means 80, so a caller that needs a port supplies its own default. A : with nothing after it is InvalidPort at parse time rather than .None, so .None only ever means the colon was absent.

Never optional in §5.3 — a missing path IS the empty path, and the empty-path case is what selects the base's path in the merge.

.None for "no ? was written"; .Some("") for a bare ?. §5.3 carries the base's query only in the first of the two cases.

.None for "no # was written". A fragment is never inherited from the base, so this one is copied straight through.

The userinfo WITHOUT the trailing @, still percent-encoded and NOT split at the : — user:pw@h answers .Some("user:pw"), where Rust splits username() from password().

.None means the authority had no @; .Some("") means it had one with nothing before it (http://@h/). Note this splits at the FIRST @ in the authority, where the WHATWG URL Standard — and so Rust's url — splits at the LAST one: http://a@b@h/ is userinfo a, host b@h here and userinfo a@b, host h there. RFC 3986 §3.2.1 does not admit a raw @ inside userinfo at all, which is why set_userinfo rejects one outright rather than picking a side.

Replace the scheme. Must be ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ).

Replace the host, or remove it with .None.

An IPv6 literal must be bracketed ([::1]) — that is how RFC 3986 §3.2.2 keeps the host's colons apart from the port's. /, ?, # and @ are rejected because each of them ENDS the host in the grammar, so accepting one would mean the next parse read a different URL than the one built.

The .None case removes the whole authority, so a following to_string renders the opaque scheme:path form.

Replace the port, or remove it with .None. Infallible: every u16 is a legal port, including 0.

Replace the path.

With a host present the path must be empty or start with /, because to_string writes scheme://host immediately followed by the path — a path of x would render http://hostx. With NO host the path must not start with //, which would render scheme://... and re-parse as an authority: a different URL than the one built.

Replace the query (WITHOUT the leading ?), or remove it with .None.

Replace the fragment (WITHOUT the leading #), or remove it with .None. The fragment is LAST in the grammar, so nothing can follow it and there is no delimiter to guard — every URI byte is legal here, including /, ? and #.

Replace the userinfo (WITHOUT the trailing @), or remove it with .None.

A @ inside userinfo is rejected: the authority splits at its FIRST @, so set_userinfo("a@b") on //host would re-parse with userinfo a and host b@host — the classic credential-confusion shape, where the host a reader sees is not the host the URL resolves to.

host:port, or the bare host when no port was written — the string a Host: header and a connect() both want, assembled once instead of at every call site.

.None exactly when host() is .None. An IPv6 host keeps its brackets, so the result stays unambiguous ([::1]:8080).

scheme://host[:port] — the same-origin key, and the prefix to hang a path off when building a sibling URL.

Two divergences from the web platform's notion of an origin, both because nothing here knows a scheme's default port: the port is included only when it was WRITTEN, so http://h and http://h:80 give different strings for the same origin; and a URL with no host answers the bare scheme rather than the opaque "null" that HTML specifies.

Resolve reference against this URL — RFC 3986 §5.3 reference resolution, and url::Url::join in Rust.

An absolute reference replaces everything. A network-path reference (//host/p) keeps only the scheme. An absolute-path reference (/p) keeps the authority. A relative reference (p, ../p) resolves against the base's DIRECTORY — https://h/a/b joined with c is https://h/a/c, because b is a document, not a directory. An empty reference keeps the base's path and query but drops its fragment; a bare #f changes only the fragment.

base := Url.parse("https://example.com/a/b").unwrap();
base.join(`c`).unwrap().to_string();       // https://example.com/a/c
base.join(`/c`).unwrap().to_string();      // https://example.com/c
base.join(`../c`).unwrap().to_string();    // https://example.com/c
base.join(`https://x/y`).unwrap().to_string(); // https://x/y

The path split on /, percent-DECODED, or .None for a URL that cannot be a base — Rust's Url::path_segments.

"Cannot be a base" means no authority: mailto:a@b has an opaque path that is not a /-separated hierarchy, and splitting it would invent structure that is not there.

A trailing / yields a final EMPTY segment, as Rust's does — that is how /a/ is distinguishable from /a.

The query string parsed as key=value pairs, percent-decoded, with + read as a space — Rust's Url::query_pairs, and the application/x-www-form-urlencoded rules a ?a=b&c=d query actually follows.

A key with no = yields an empty value (?flag is ("flag", "")), an empty pair between two &s is skipped, and a value containing = keeps everything after the FIRST one (?a=b=c is ("a", "b=c")). Order and duplicates are preserved: ?a=1&a=2 is two pairs.

Render self as the text a USER should read — Rust's Display::fmt, not its Debug. Hand-written (or generated by derive(Error) from a per-variant format string) whenever the structural form would be wrong.

Render self under spec. An unrecognised spec degrades to the plain to_string() rendering rather than failing.

The error that caused this one, or .None at the root of the chain.

Rust's Error::source. Defaulted to .None, so an error with nothing underneath it implements the trait by saying only what it is; a wrapper overrides it to hand back what it wrapped. Walking the chain to the root cause is not expressible yet — the returned Dyn loses the Error trait on an erased receiver, so a caller can print one link but cannot follow it (#521, issues/self-trait-in-a-return-type-loses-the-trait-on-an-erased-receiver.md).