Url0.33.0

Overview
Properties
Methods

class Url

A URL, as defined by RFC 3986. RFC 6874 IPv6 zone literals are also supported.

Known subtypes in package:
Known usages in package:
All versions:

Every component is held percent-encoded, in its raw property, such as rawPath: Url() encodes whatever a component cannot hold literally, and a component that is set by hand, or amended, has to be encoded already. The percent-decoded form of each component is available without the raw prefix, such as path.

Facts:

net.Url("https://example.com/a b").rawPath == "/a%20b"
net.Url("https://example.com/a b").path == "/a b"
net.Url("https://example.com/a%20b").rawPath == "/a%20b"

Properties

link

scheme: String(isValidScheme(this))?

The scheme, without the trailing :, or null if this is a relative reference.
link

rawUserInfo: String(rawHost != null, isValidUserInfo(this))?

The percent-encoded userinfo, without the trailing @, or null if this URL has none.

Only a URL with a rawHost can have userinfo.
link

hidden

userInfo: String?

The percent-decoded rawUserInfo.
link

rawHost: String(isValidHost(this))?

The percent-encoded host, or null if this URL has no authority.

A null host is not the same as an empty one: file:/tmp has no host, file:///tmp has an empty one.

An IPv6 address must be enclosed in brackets, as in [::1]. It may carry a zone identifier, as described in RFC 6874. Anything else is a registered name, which cannot contain [, ] or : literally.
link

hidden

host: String?

The percent-decoded rawHost.
link

rawPort: String(rawHost != null, matches(Regex(#"\d*"#)))?

The port, without the leading :, or null if this URL states none.

Only a URL with a rawHost can have a port.
link

hidden
port: UInt16?

The number that rawPort states.
This is null if rawPort is null, or if rawPort is not parseable as a UInt16.

Facts:
```
net.Url("https://example.com:8080/").port == 8080
net.Url("https://example.com:/").port == null
```
link

rawPath: String(isValidPath(this, scheme != null, rawHost != null))

The percent-encoded path, or the empty string if this URL has none.

With a rawHost, the path is empty or starts with /. Without one, it may be rootless, as in mailto:user@example.com. Without a scheme, its first segment cannot contain :.

To change the path without encoding it first, use resolve(), which is as lenient as Url(). Unlike amending, this drops rawQuery and rawFragment.
link

hidden
path: String

The percent-decoded rawPath.
An encoded / is decoded like any other octet, so it cannot be distinguished from a / that separates segments. pathSegments disambiguates between separator and literal / characters.

Facts:
```
net.Url("https://example.com/a%2Fb/c").path == "/a/b/c"
net.Url("https://example.com/a%2Fb/c").pathSegments == List("a/b", "c")
```
link

rawQuery: String(isValidQuery(this))?

The percent-encoded query, without the leading ?, or null if this URL has none.

The empty string is a URL ending in a bare ?.
link

hidden

query: String?

The percent-decoded rawQuery.

Unlike queryParameters, this does not read rawQuery as application/x-www-form-urlencoded, so a + is kept as is.
link

rawFragment: String(isValidFragment(this))?

The percent-encoded fragment, without the leading #, or null if this URL has none.

The empty string is a URL ending in a bare #.
link

hidden

fragment: String?

The percent-decoded rawFragment.
link

stringValue: String

The serialization of this URL.
link

hidden

isAbsolute: Boolean

Tells if this URL is absolute, that is, has a non-null scheme.
link

hidden

hasAbsolutePath: Boolean

Tells if this URL's path is absolute, that is, starts with /.
link

authority: String?

The authority, without the leading //, or null if this URL has none.

A URL has an authority exactly when it has a rawHost. This is rawUserInfo, rawHost and rawPort joined back together.
link
hostKind: ("name"|"ipv4"|"ipv6"|"ipvFuture")?

What rawHost is, or null if this URL has no authority.
- "ipv6": an IPv6 address, such as [::1]
- "ipvFuture": an IP address of a version that RFC 3986 leaves for the future
- "ipv4": an IPv4 address in dotted-decimal form, such as 192.0.2.1
- "name": any other host, a registered name
Facts:
```
net.Url("https://example.com/").hostKind == "name"
net.Url("https://192.0.2.1/").hostKind == "ipv4"
net.Url("https://[::1]/").hostKind == "ipv6"
net.Url("/foo").hostKind == null
```
link
zoneId: String?

The percent-decoded zone identifier of an IPv6 rawHost, as described in RFC 6874, or null if it states none.
Facts:
```
net.Url("http://[fe80::1%25eth0]/").zoneId == "eth0"
net.Url("http://[fe80::1]/").zoneId == null
```
link
pathSegments: List<String>

The percent-decoded segments of rawPath.
pathSegments does not tell if the path is absolute or not. A relative URL reference "a/b" also has path segments List("a", "b"). To disambiguate between the two, use hasAbsolutePath.

Facts:
```
net.Url("https://example.com/a/b%20c").pathSegments == List("a", "b c")
net.Url("https://example.com/a/b%2Fc").pathSegments == List("a", "b/c")
```
link
queryParameters: Mapping<String, Listing<String>>?

The percent-decoded parameters of rawQuery, or null if this URL has no query.
rawQuery is read as application/x-www-form-urlencoded. A name that repeats holds the values of all its occurrences, in the order they are written. A parameter that states no = holds no value at all, and is left out; this is not the same as a bare =, which gives it the empty string.

Facts:
```
net.Url("https://example.com/?q=a+b&q=c").queryParameters["q"] == new Listing { "a b"; "c" }
net.Url("https://example.com/?").queryParameters.isEmpty
net.Url("https://example.com/").queryParameters == null
```
link

hidden
normalized: Url

The normalized version of this URL, following syntax-based normalization as described in section 6.2.2 of RFC 3986.
scheme and rawHost are lowercased, as they are case-insensitive. Percent-encoding is normalized: an octet standing for an unreserved character is decoded, and any other octet is kept, with its hex digits uppercased.

Dot segments (./ and ../) are only removed from an absolute rawPath. A URL with a rawHost and no path is given the path /, which names the same resource.

Does not perform normalization that requires knowing the scheme, such as removing a default port (see section 6.2.3).

Facts:
```
net.Url("HTTPS://Example.com/%7Euser").normalized == net.Url("https://example.com/~user")
net.Url("https://example.com/a/b/../c").normalized.rawPath == "/a/c"
net.Url("https://example.com").normalized.rawPath == "/"
```

Methods(show inherited)

link

function

Any.getClass(): Class<this> (pkl.base)Source

Returns the class of this.

link

function

toString(): String

The serialization of this URL.

Facts:

net.Url("https://example.com/a b").toString() == "https://example.com/a%20b"
net.Url("https://example.com/é").toString() == "https://example.com/%C3%A9"
net.Url("HTTPS://example.com").toString() == "HTTPS://example.com"

link

function

Any.ifNonNull<Result>(transform: (this) -> Result): Result? (pkl.base)Source

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.
link

function

Typed.hasProperty(name: String): Boolean (pkl.base)Source

Tells if this object has a property with the given name.
link

function

Typed.getProperty(name: String): unknown (pkl.base)Source

Returns the value of the property with the given name.

Throws if a property with this name does not exist.
link

function

Typed.getPropertyOrNull(name: String): unknown? (pkl.base)Source

Returns the value of the property with the given name.

Returns null if a property with this name does not exist.
link

function

Typed.toDynamic(): Dynamic (pkl.base)Source

Converts this object to a Dynamic object.
link

function

Typed.toMap(): Map<String, unknown> (pkl.base)Source

Converts this object to a Map.
link

function
resolve(ref: String|Url): Url

Resolves ref against this URL.
ref is either a relative reference, which is resolved against this URL, or an absolute URL, which replaces it entirely. Dot segments (./ and ../) are removed from the result's path, normalizing it.

Throws if ref is a string that cannot be parsed, or if this URL is itself a relative reference.

Facts:
```
net.Url("https://example.com/a/b").resolve("../c").toString() == "https://example.com/c"
net.Url("https://example.com/a/b").resolve("#top").toString() == "https://example.com/a/b#top"
net.Url("foo:/a").resolve("..//x").toString() == "foo:/.//x"
```
link

function
equals(other: Url): Boolean

Tells if this URL is equal to other according to syntax-based normalization as described in section 6.2.2 of RFC 3986.
Returns true if the normalized versions of this and other are the same, and false otherwise.

Facts:
```
net.Url("HTTPS://Example.com/%7Euser").equals(net.Url("https://example.com/~user"))
!(net.Url("https://example.com/a%2Fb").equals(net.Url("https://example.com/a/b")))
!(net.Url("https://example.com:443/").equals(net.Url("https://example.com/")))
```
link

function

isValidUserInfo(value: String): Boolean

Tells if value is a percent-encoded userinfo.
link

function

isValidScheme(value: String): Boolean

Tells if value is a scheme.
link

function

isValidHost(value: String): Boolean

Tells if value is a percent-encoded host.
link

function

isValidPath(value: String, hasScheme: Boolean, hasAuthority: Boolean): Boolean

Tells if value is a percent-encoded path that can sit next to a scheme and an authority, or, when hasScheme or hasAuthority is false, next to no scheme or no authority.
link

function

isValidQuery(value: String): Boolean

Tells if value is a percent-encoded query.
link

function

isValidFragment(value: String): Boolean

Tells if value is a percent-encoded fragment.