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

ValueError if the string is not a valid URL.

Example

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

Fields

fragment

The decoded fragment string, or nil if absent.

host

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

name

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

The decoded password, or nil if not present.

path

The serialized path component.

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

port

The explicit port number, or nil if not present.

query @ Iter[Tuple[Str, Str]]

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

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

scheme

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

segments @ std.Seq[Str]

Immutable array-like view of decoded path segments.

Returns

Iter of Str values.

Example

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

username

The decoded username, or nil if not present.

Methods

`(div) other`

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.

Example

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

`(eq) other`

Compares two URLs by their parsed values.

`(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`		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`.