Skip to content

uri

class URIBuilder

URIBuilder¶

Fluent builder for constructing URIs from raw (unencoded) components.

Each setter accepts raw text and automatically percent-encodes it for the target component. The build() method validates the assembled URI and returns a URI val.

match URIBuilder
  .set_scheme("https")
  .set_host("example.com")
  .set_path("/api/users")
  .add_query_param("name", "Jane Doe")
  .set_fragment("top")
  .build()
| let u: URI val =>
  // u.string() == "https://example.com/api/users?name=Jane%20Doe#top"
| let e: URIBuildError val =>
  // handle error
end

Use from() to copy an existing URI's pre-encoded components into the builder for modification. Since from() copies pre-encoded values, do not pass an existing URI's encoded component (e.g., uri.query) to a setter like set_query() — that would double-encode it. Instead, use from() and then modify only the components you want to change.

class ref URIBuilder

Constructors¶

create¶

Create an empty builder with all components unset.

new ref create()
: URIBuilder ref^

Returns¶

URIBuilder ref^

from¶

Copy pre-encoded components from an existing URI.

Authority components (userinfo, host, port) are decomposed from the URI's authority. All values are copied as-is without re-encoding.

new ref from(
  uri: URI val)
: URIBuilder ref^

Parameters¶

uri: URI val

Returns¶

URIBuilder ref^

Public Functions¶

set_scheme¶

Set the URI scheme from raw text.

The scheme is validated on build() — it must match [A-Za-z][A-Za-z0-9+-.]* per RFC 3986 section 3.1. No encoding is needed for schemes (they are ASCII-only).

fun ref set_scheme(
  scheme: String val)
: URIBuilder ref

Parameters¶

scheme: String val

Returns¶

URIBuilder ref

clear_scheme¶

Remove the scheme component.

fun ref clear_scheme()
: URIBuilder ref

Returns¶

URIBuilder ref

set_userinfo¶

Set the userinfo component from raw (unencoded) text.

The input is percent-encoded for the userinfo component. If no host is set, an empty host is created automatically (userinfo requires an authority).

fun ref set_userinfo(
  userinfo: String val)
: URIBuilder ref

Parameters¶

userinfo: String val

Returns¶

URIBuilder ref

clear_userinfo¶

Remove the userinfo component.

fun ref clear_userinfo()
: URIBuilder ref

Returns¶

URIBuilder ref

set_host¶

Set the host component from raw (unencoded) text.

If the input starts with [, it is treated as an IP-literal and stored as-is (validated on build()). Otherwise, it is percent-encoded as a reg-name. IPv6 addresses must include brackets (e.g., [::1]).

fun ref set_host(
  host: String val)
: URIBuilder ref

Parameters¶

host: String val

Returns¶

URIBuilder ref

clear_host¶

Remove the host component.

Also clears userinfo and port, since they require an authority.

fun ref clear_host()
: URIBuilder ref

Returns¶

URIBuilder ref

set_port¶

Set the port number.

If no host is set, an empty host is created automatically (port requires an authority).

fun ref set_port(
  port: U16 val)
: URIBuilder ref

Parameters¶

port: U16 val

Returns¶

URIBuilder ref

clear_port¶

Remove the port component.

fun ref clear_port()
: URIBuilder ref

Returns¶

URIBuilder ref

set_path¶

Set the path component from raw (unencoded) text.

The input is percent-encoded for the path component. Path structure (slashes) is preserved — only characters that need encoding are encoded.

fun ref set_path(
  path: String val)
: URIBuilder ref

Parameters¶

path: String val

Returns¶

URIBuilder ref

append_path_segment¶

Append a single path segment from raw (unencoded) text.

The segment is encoded with slash (/) also encoded (as %2F) so it remains a single segment. A / separator is prepended automatically.

fun ref append_path_segment(
  segment: String val)
: URIBuilder ref

Parameters¶

segment: String val

Returns¶

URIBuilder ref

set_query¶

Set the query component from raw (unencoded) text.

The input is percent-encoded for the query component. Structure characters & and = are preserved since they are sub-delimiters allowed in query. For individual key-value pairs with full encoding, use add_query_param.

fun ref set_query(
  query: String val)
: URIBuilder ref

Parameters¶

query: String val

Returns¶

URIBuilder ref

clear_query¶

Remove the query component.

After clearing, no ? delimiter appears in the output. To produce a trailing ? with no value, use set_query("") instead.

fun ref clear_query()
: URIBuilder ref

Returns¶

URIBuilder ref

add_query_param¶

Add a query parameter from raw (unencoded) key and value.

Both the key and value are encoded with =, &, and + also encoded (in addition to standard query encoding) so they are safe as individual parameter components. Parameters are appended with & as separator.

fun ref add_query_param(
  key: String val,
  value: String val)
: URIBuilder ref

Parameters¶

key: String val
value: String val

Returns¶

URIBuilder ref

set_fragment¶

Set the fragment component from raw (unencoded) text.

The input is percent-encoded for the fragment component.

fun ref set_fragment(
  fragment: String val)
: URIBuilder ref

Parameters¶

fragment: String val

Returns¶

URIBuilder ref

clear_fragment¶

Remove the fragment component.

After clearing, no # delimiter appears in the output. To produce a trailing # with no value, use set_fragment("") instead.

fun ref clear_fragment()
: URIBuilder ref

Returns¶

URIBuilder ref

build¶

Validate and assemble the URI from the current components.

Returns InvalidScheme if the scheme is set but does not match [A-Za-z][A-Za-z0-9+-.]*. Returns InvalidHost if an IP-literal host is malformed. Returns the assembled URI val on success.

fun box build()
: (URI val | InvalidScheme val | InvalidPort val | 
    InvalidHost val)

Returns¶

(URI val | InvalidScheme val | InvalidPort val | InvalidHost val)