Url

Structured URL value with parsed access to components and decoded path/query iteration.

Constructor

Url value

Parses a URL string or copies an existing Url.

Parameters

Name	Type	Description
value	(Str | Url)	URL to parse or copy.

Errors

DataError if the string is not a valid URL.

Example

let base = Url "https://example.com/api"
let copy = Url $base

Fields

fragment @ (Str | nil) ^[get]

The decoded fragment string, or nil if absent.

host @ (Str | nil) ^[get]

The host string, or nil if the URL has no host.

name @ (Str | nil) ^[get]

The decoded last path component, or nil if there is no filename.

This returns nil for URLs whose path is empty or ends with /.

password @ (Str | nil) ^[get]

The decoded password, or nil if not present.

path @ Str ^[get]

The serialized path component.

This preserves percent-encoding. Use segments for decoded path segments.

port @ (Int | nil) ^[get]

The explicit port number, or nil if not present.

query @ Map[Str, Str] ^[get]

Immutable dictionary-like view of decoded query pairs.

Duplicate keys and original ordering are preserved.

Example

let url = Url "https://example.com?q=a+b&q=c"
let pairs = [...url.query]
assert_eq $pairs[0][0] "q"
assert_eq $pairs[0][1] "a b"
assert_eq $pairs[1][1] "c"

Open in playground

query_raw @ (Str | nil) ^[get]

The raw query string without the leading ?, or nil if absent.

scheme @ Str ^[get]

The URL scheme, such as "https" or "file".

segments @ Seq[Str] ^[get]

The decoded path segments, as a read-only view.

Example

let url = Url "https://example.com/a%20b/c"
assert_eq [...url.segments] ["a b", "c"]

username @ (Str | nil) ^[get]

The decoded username, or nil if not present.

Methods

(div) other -> Url

Appends a decoded path segment and returns a new Url.

The segment is percent-encoded as needed. A value starting with / is an absolute path, with optional query and fragment, relative to this URL's scheme and authority.

Parameters

Name	Type	Description
other	Str	Path segment or absolute path.

Errors

Exception	Condition
ValueError	This URL has no path to extend, such as a mailto: URL
DataError	An absolute path is not a valid URL reference

Example

let base = Url "https://example.com"
let child = (base / "a b" / "c/d")
assert_eq $child.path "/a%20b/c%2Fd"

(eq) other -> Bool

Compares two URLs by their parsed values.

Parameters

Name	Type	Description
other	Value

(lt) other -> Bool

Orders two URLs by their parsed values.

Parameters

Name	Type	Description
other	Url

(str)() -> Str

Returns the canonical serialized URL.

with_fragment fragment -> Url

Returns a new Url with its fragment replaced.

Pass nil to remove the fragment.

Parameters

Name	Type	Description
fragment	(Str | nil)	Fragment string or nil.

with_query **keys … -> Url

Returns a new Url with its query rebuilt from decoded key/value pairs.

Pairs come from either a single iterable or key arguments, not both.

Parameters

Name	Type	Description
pairs?	Iterable[Tuple[Value, Value]]	Decoded key/value pairs.
**keys	Value	Query values keyed by argument name.

Example

let base = Url "https://example.com"
let url = base.with_query q: "a b" tag: "x/y"
assert_eq $url.query_raw "q=a+b&tag=x%2Fy"
assert_eq $base.with_query({q: "a b", tag: "x/y"}) $url

with_query_raw query -> Url

Returns a new Url with its raw query replaced.

Pass nil to remove the query.

Parameters

Name	Type	Description
query	(Str | nil)	Raw query string or nil.