`std/uri`

Uniform Resource Identifiers as values: Uri and UriReference after RFC 3986, read and normalized at construction, so ==, hash() and compare() are over the canonical form; IRIs (RFC 3987) read as the URI they stand for and shown back by iriText(); Urn after RFC 8141; DataUri after RFC 2397; UriTemplate after RFC 6570, typed against the fields it fills, and the routes of TemplateRoutes built from it; the file: bridge to Path after RFC 8089; and the application/x-www-form-urlencoded codec of HTML forms. Schemes is what a driver of a scheme says it answers to, which a registry of drivers dispatches on (std/storage).

A string literal where a Uri, a UriReference or a UriTemplate is expected is read by the compiler where it is written, and one that is none is an error at that line (docs/design/URI.md section 9).

Nothing in std/uri touches anything - no network, no file system, no capability. An IP literal host is an address of std/ip, and resolving a name or opening a connection is std/network's. Uri and UriError are in the prelude; everything else is an import (docs/design/URI.md).

const base: Uri = "https://example.test/guide/start.html"
const link: UriReference = "../reference/index.html#top"
print link.resolved(against: base)

Modules

std/uri/authority[Authority] and [Host]: the [userInfo "@"] host [":" port] of a URI, read and normalized (RFC 3986 section 3.2).
std/uri/charactersThe character classes of RFC 3986 and the percent-encoding every other module of std/uri is written over.
std/uri/data[DataUri]: a data: URI read into the parts RFC 2397 gives it - a media type, its parameters and the bytes the URI carries in place (docs/design/URI.md section 7).
std/uri/errorUriError: what a text is refused for as a URI, a URI reference, a URN, a file: path or a URI template.
std/uri/formapplication/x-www-form-urlencoded, the convention of HTML forms for a query and for a form body, as the WHATWG URL Standard (section 5) defines it.
std/uri/repaired[repaired], the repairs the WHATWG URL parser makes before it parses (docs/design/URI.md section 6).
std/uri/route[TemplateCase], [TemplateRoute] and [TemplateRoutes]: URI templates typed against the cases of one type, which is what a router of std/web is built from (docs/design/WEB.md, decision D5; docs/design/URI.md section 9a).
std/uri/schemes[Schemes], the one member every registry of drivers dispatches on (docs/design/URI.md section 11).
std/uri/template[UriTemplate]: RFC 6570, all four levels - read once, expanded into a URI reference, and matched backwards where the template allows it (docs/design/URI.md section 9a).
std/uri/uri[Uri] and [UriReference]: RFC 3986, read and normalized at construction, with Equals, Hash and Compare over the normalized form (docs/design/URI.md sections 3 to 5).
std/uri/urn[Urn]: a urn: URI read into the parts RFC 8141 gives it - a namespace identifier, a namespace-specific string, and the r-, q- and f-components (docs/design/URI.md section 7).

Everything

type AuthorityThe [userInfo "@"] host [":" port] of a URI.
type DataParameterOne ;name=value of a data: URI's media type, as RFC 2397 section 3 writes them.
type DataUriA data: URI per RFC 2397: data:[<media type>][;<name>=<value>]*[;base64],<data>, with the data the bytes the URI carries - percent-decoded, or Base64-decoded when the ;base64 flag ends the header.
extend DataUri with TryFrom<Uri, UriError>A URI read as a data: URI (RFC 2397 section 3): no authority, a ,, a header of an optional media type that is type/subtype, parameters that are each name=value, and a last base64 flag, and data that is valid Base64 when the flag is set.
type HostWhere an authority points.
extend List<(String, String)>Adds formEncoded to a list of name and value pairs, to write it as application/x-www-form-urlencoded.
extend Path with TryFrom<Uri, UriError>A file: URI read as a Path, in every form RFC 8089 and its appendices know: file:///x, file:/x, file://localhost/x, file:///C:/x, file:///C|/x, file:C:/x and file://server/share/x.
extend Path with TryFrom<UriReference, UriError>A URI reference read as a Path: a file: URI as [Path.tryFrom] of a Uri reads it, and a relative-path reference as the relative path it spells.
fn repairedThe repairs a browser makes to what a person typed, before it reads it as a URL: leading and trailing control characters and spaces (U+0000 to U+0020) are dropped, every tab, line feed and carriage return anywhere in the text is removed, and a \ is read as / in the part before the first ? or # - when the scheme is one of the special ones (http, https, ws, wss, ftp, file, in any case) or the text has no scheme.
fn routeThe route of one case: route("/orders/{id}", to: Route.Order).
trait SchemesThe schemes a driver answers to.
extend StringAdds percentDecoded to a string, to read the percent escapes of a URI component.
extend StringAdds formDecoded to a string, to read it as application/x-www-form-urlencoded.
extend String with From<UriTemplate<TemplateValues>>The way back out of an untyped [UriTemplate], and with [UriTemplate.tryFrom] its conversion pair.
extend String with From<Uri>The way back out, and with [Uri.tryFrom] the one conversion pair of the capsule.
extend String with From<UriReference>The way back out of [UriReference], and with [UriReference.tryFrom] its conversion pair.
type TemplateCaseOne case of Value, named where it is written: Route.Order where a TemplateCase<Route> is expected is the case Order, and not the function that constructs one (docs/design/URI.md section 9a).
type TemplateRouteA template and the case of Value its variables fill: one line of a router.
type TemplateRoutesEvery route of Value, checked to cover each of its cases: a reference is matched against them in order and read into the case of the first that matches, and a value is linked through the route of its own case.
type TemplateValueWhat a variable of a template holds: RFC 6570 section 2.3's three kinds of value.
alias TemplateValuesThe variables of a template read at run time: whatever the map holds, by name.
type TemplateVariableOne variable of a template, as a value that fills it sees it ([UriTemplate.templateVariables]).
extend Uri with From<DataUri>The URI a data: URI is.
type UriA URI per RFC 3986 section 3: a scheme, and an authority, a path, a query and a fragment after it.
extend Uri with TryFrom<String, UriError>A text read as a URI and normalized on the way in.
extend Uri with TryFrom<Path, UriError>A Path written as a file: URI.
extend Uri with From<Urn>The URI a URN is.
type UriErrorWhy a text is not what it was read as.
type UriReferenceA URI reference per RFC 3986 section 4.1: a [Uri], or a relative reference - ../a, /b?c, //host/d, #top - that means something only against a base.
extend UriReference with TryFrom<String, UriError>A text read as a URI reference - a URI or a relative reference - and normalized on the way in.
extend UriReference with From<Uri>Every URI is a reference.
extend UriReference with TryFrom<Path, UriError>A Path written as a URI reference: an absolute path as a file: URI - the root becomes the authority or the first segment - and a relative path as a relative reference.
type UriTemplateAn RFC 6570 URI template: literal text and {…} expressions, read once with [UriTemplate.tryFrom] and expanded with variables into a URI reference - "/orders/{id}{?fields*}" with id = 7 and fields = ["a", "b"] is /orders/7?fields=a&fields=b.
type UrnA URN per RFC 8141: urn:<namespace>:<specific>, with the namespace identifier lower case and everything else as the Uri it was read from normalized it.
extend Urn with TryFrom<Uri, UriError>A URI read as a URN (RFC 8141 section 2): no authority, a namespace identifier of two to thirty-two letters, digits and - that neither starts nor ends with a -, a :, a namespace-specific string that is not empty and does not start with /, and a query that is an r-component, a q-component or both.