silk.url.url.

Parse, serialize, and change URLs as the WHATWG URL Standard specifies, the way web browsers and JavaScript's URL do.

When to use#

Use Url for URLs that come from the web or from people: links, fetch targets, and request URLs. It accepts what browsers accept and normalizes it the same way. For strict RFC 3986 URIs, use silk.uri.uri.

Details#

A Url holds one ASCII string, its serialization, and the positions of its components, so reading a component does not allocate. Url.parse resolves a relative input against a base. The setters, such as Url.setPathname, follow the URL Standard's API setters: an input that cannot change the component leaves the URL as it is. Non-ASCII text is percent-encoded as UTF-8 and domains are converted with UTS #46, so the serialization is always ASCII.

Errors#

  • OutOfMemoryError from every function that allocates.

Examples#

Parse a URL and read its parts#

silk
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.core.effect { Effect }
import silk.core.option { Option }
import silk.url.url { Url }

pub effect fn main() -> i32
  ! OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let parsed = run Url.parse("HTTPS://Example.COM:443/a/./b/../c?x=1#top", Option<&Url>.none())
    |> Effect.provideMut<Allocator>(&mut allocator)
  let url = match move parsed {
    Option<Url>.Some { value } => move value
    Option<Url>.None => { return 1 }
  }
  if Url.href(&url) != "https://example.com/a/c?x=1#top" || Url.pathname(&url) != "/a/c" {
    return 1
  }
  return 0
}

Import as Url with import silk.url.url { Url }.

Public declarations: 2.

UrlComponents#

silk
pub struct UrlComponents

The positions of the parts of a URL's serialization, from Url.components.

Details#

Every position is a byte offset into Url.href. They let code that keeps the serialization as its own string, such as a JavaScript binding, take each getter's text as a slice.

Field schemeEnd#

silk
pub schemeEnd: usize

The position of the : after the scheme.

Field userStart#

silk
pub userStart: usize

The start of the user name. The user name is [userStart, usernameEnd).

Field usernameEnd#

silk
pub usernameEnd: usize

The end of the user name.

Field passwordEnd#

silk
pub passwordEnd: usize

The end of the password. The password is [usernameEnd + 1, passwordEnd) when passwordEnd is greater than usernameEnd, and empty otherwise.

Field hostStart#

silk
pub hostStart: usize

The start of the host.

Field hostEnd#

silk
pub hostEnd: usize

The end of the host. The port follows it after : when the URL has one.

Field hostKind#

silk
pub hostKind: UrlHostKind

The kind of the host. The host and port text is [hostStart, pathStart) unless it is Absent.

Field port#

silk
pub port: Option<u16>

The port, or None when the URL has no port or the port is the default of the scheme.

Field pathStart#

silk
pub pathStart: usize

The start of the path.

Field queryStart#

silk
pub queryStart: Option<usize>

The position of the ? before the query, or None when the URL has no query.

Field fragmentStart#

silk
pub fragmentStart: Option<usize>

The position of the # before the fragment, or None when the URL has no fragment.

Url#

silk
pub struct Url

A URL as the WHATWG URL Standard defines it: its serialization and the positions of its components.

Details#

The serialization is scheme:, then //, user information, the host, and the port when the URL has a host, then the path, ? and the query, and # and the fragment. A Url owns it. The getters return views of it, with the same text as the getters of JavaScript's URL.

Gotchas#

A URL with an opaque path, such as mailto:a@example.com, has a path that is one string, not segments, and Url.setPathname does not change it.

Implementation Url#

silk
impl Url

Associated function parse#

silk
pub effect fn parse(input: string, base: Option<&Url>) -> Option<Url>
    ! OutOfMemoryError
    ? &mut Allocator

Parses input as a URL, relative to base when it is given. Returns None if input is not a valid URL.

Details#

It is the URL Standard's basic URL parser with UTF-8 encoding. Leading and trailing C0 controls and spaces are removed, and so are all tabs and newlines. input can be relative only when base is given.

Errors#

  • OutOfMemoryError if the Allocator fails.

Associated function canParse#

silk
pub effect fn canParse(input: string, base: Option<&Url>) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Returns whether input is a valid URL, relative to base when it is given.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method copy#

silk
pub effect fn copy(self: &Self) -> Url
    ! OutOfMemoryError
    ? &mut Allocator

Returns a copy of self.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method href#

silk
pub fn href(self: &Self) -> string

Returns the serialization of the URL, as JavaScript's URL.href does. It is ASCII.

Method hrefWithoutFragment#

silk
pub fn hrefWithoutFragment(self: &Self) -> string

Returns the serialization without the fragment and its #.

Method protocol#

silk
pub fn protocol(self: &Self) -> string

Returns the scheme followed by :, as JavaScript's URL.protocol does: https:.

Method scheme#

silk
pub fn scheme(self: &Self) -> string

Returns the scheme, without the :: https. It is lowercase.

Method username#

silk
pub fn username(self: &Self) -> string

Returns the percent-encoded user name, or an empty string.

Method password#

silk
pub fn password(self: &Self) -> string

Returns the percent-encoded password, or an empty string.

Method host#

silk
pub fn host(self: &Self) -> string

Returns the serialized host and the port after : if the URL has a port, as JavaScript's URL.host does: example.com:8080. It is empty when the URL has no host.

Method hostname#

silk
pub fn hostname(self: &Self) -> string

Returns the serialized host, as JavaScript's URL.hostname does. An IPv6 address is in brackets. It is empty when the URL has no host.

Method components#

silk
pub fn components(self: &Self) -> UrlComponents

Returns the positions of the parts of Url.href.

Method hostKind#

silk
pub fn hostKind(self: &Self) -> UrlHostKind

Returns the kind of the host.

Method port#

silk
pub fn port(self: &Self) -> string

Returns the port in decimal, or an empty string when the URL has no port or the port is the default of the scheme.

Method portNumber#

silk
pub fn portNumber(self: &Self) -> Option<u16>

Returns the port, or None when the URL has no port or the port is the default of the scheme.

Method pathname#

silk
pub fn pathname(self: &Self) -> string

Returns the path, as JavaScript's URL.pathname does: /a/b, or the opaque path.

Method search#

silk
pub fn search(self: &Self) -> string

Returns ? and the query, or an empty string when the query is absent or empty, as JavaScript's URL.search does.

Method query#

silk
pub fn query(self: &Self) -> Option<string>

Returns the query without ?, or None when the URL has no query.

Method hash#

silk
pub fn hash(self: &Self) -> string

Returns # and the fragment, or an empty string when the fragment is absent or empty, as JavaScript's URL.hash does.

Method fragment#

silk
pub fn fragment(self: &Self) -> Option<string>

Returns the fragment without #, or None when the URL has no fragment.

Method hasOpaquePath#

silk
pub fn hasOpaquePath(self: &Self) -> bool

Returns whether the URL has an opaque path, such as mailto:a@example.com.

Method isSpecial#

silk
pub fn isSpecial(self: &Self) -> bool

Returns whether the scheme is special: http, https, ws, wss, ftp, or file.

Method appendOrigin#

silk
pub effect fn appendOrigin(self: &Self, output: &mut String) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Appends the serialization of the URL's origin to output, as JavaScript's URL.origin does.

Details#

The origin of an http, https, ws, wss, or ftp URL is its scheme, host, and port: https://example.com:8443. A blob URL has the origin of the URL in its path when that URL is http or https. Every other URL has an opaque origin, serialized as null.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setHref#

silk
pub effect fn setHref(self: &mut Self, input: string) -> bool
    ! OutOfMemoryError
    ? &mut Allocator

Replaces the URL with input parsed with no base, and returns true. Returns false and leaves the URL as it is when input is not a valid URL, as JavaScript's href setter does.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setProtocol#

silk
pub effect fn setProtocol(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the scheme from input up to its first :, as JavaScript's protocol setter does.

Details#

A special scheme cannot change to a scheme that is not special or the reverse, a URL with credentials or a port cannot become a file URL, and a file URL with an empty host keeps its scheme. A port that is the new scheme's default is removed.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setUsername#

silk
pub effect fn setUsername(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the user name to input, percent-encoded, as JavaScript's username setter does. A URL with no host, an empty host, or the file scheme keeps its user name.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setPassword#

silk
pub effect fn setPassword(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the password to input, percent-encoded, as JavaScript's password setter does. A URL with no host, an empty host, or the file scheme keeps its password.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setHost#

silk
pub effect fn setHost(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the host and, after a :, the port from input, as JavaScript's host setter does. An invalid host, or a URL with an opaque path, leaves the URL as it is.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setHostname#

silk
pub effect fn setHostname(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the host from input, without the port, as JavaScript's hostname setter does. An invalid host, or a URL with an opaque path, leaves the URL as it is.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setPort#

silk
pub effect fn setPort(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the port from the digits at the start of input, as JavaScript's port setter does.

Details#

An empty input removes the port. A port that is the scheme's default is removed. Text that does not start with a digit, or a value above 65535, leaves the URL as it is. A URL with no host, an empty host, or the file scheme keeps its port.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setPathname#

silk
pub effect fn setPathname(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the path from input, as JavaScript's pathname setter does. . and .. segments are resolved. A URL with an opaque path keeps its path.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setSearch#

silk
pub effect fn setSearch(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the query from input, without a leading ?, as JavaScript's search setter does. An empty input removes the query.

Errors#

  • OutOfMemoryError if the Allocator fails.

Method setHash#

silk
pub effect fn setHash(self: &mut Self, input: string) -> ()
    ! OutOfMemoryError
    ? &mut Allocator

Sets the fragment from input, without a leading #, as JavaScript's hash setter does. An empty input removes the fragment.

Errors#

  • OutOfMemoryError if the Allocator fails.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page