kex docs Standard Library 0.4.0-alpha kex.run ↗

URI

module URI

record URI

Strict RFC 3986 URI values, hierarchical URLs, query strings, and HTML form encoding. Parsing preserves caller spelling; normalization is always explicit.

using URI

let base = URL.parse("https://example.test/a/").try
let reference = URI.parse("../items?limit=10").try
base.resolve(reference).try.string

A parsed RFC 3986 URI reference. Construction is strict; use parse rather than building this representation directly. string preserves the spelling supplied by the caller, while normalize is explicit.

Fields

source
String

record URL

An absolute hierarchical URI with an authority component, such as an HTTP URL. Unlike a general URI, a URL always has a scheme and host, which makes accessors such as scheme and host total.

Fields

source
String

record Host

A host's display spelling and normalized ASCII/IDNA spelling.

Fields

display
String
ascii
String

record Query

Ordered URI query entries. None distinguishes a bare key from key=.

Order and duplicates matter in real APIs: tag=kex&tag=beam must not become a map with one value silently discarded.

Fields

entries
[(String, String?)]

record Form

Ordered application/x-www-form-urlencoded entries.

This is deliberately separate from Query: HTML forms encode spaces as plus signs, while a generic URI query treats a plus as an ordinary +.

Fields

entries
[(String, String?)]

record URIError

A typed URI parsing, conversion, or resolution failure.

Fields

kind
URIErrorKind
message
String
position
Integer?

type URIErrorKind

Stable URI failure categories.

Variants

  • InvalidSyntax
  • InvalidEscape
  • InvalidAuthority
  • InvalidPort
  • NonASCII
  • NotAbsolute
  • NotHierarchical
  • MissingAuthority
  • UnsupportedScheme

function parse

Strictly parses an ASCII RFC 3986 URI reference.

Relative references are valid here. Use URL.parse when the input must be a complete hierarchical URL with a scheme and authority.

parse(text) : String -> Result<URI, URIError>
Parameters
text String
an absolute URI or relative reference

Returns: Result<URI, URIError> — the reference or a precise syntax error

Examples

Resolving an image link found in a document

let reference = URI.parse("../images/logo.svg").try
let absolute = base.resolve(reference).try

function fromIRI

Converts a Unicode IRI to an ASCII URI using IDNA and UTF-8 percent encoding.

Use this for human-entered international addresses. parse is intentionally stricter and accepts only an already encoded ASCII URI.

fromIRI(text) : String -> Result<URI, URIError>
Parameters
text String
a Unicode internationalized resource identifier

Returns: Result<URI, URIError> — the converted URI or a conversion error

Examples

Turning a pasted international address into a request URI

let target = URI.fromIRI("https://münich.example/straße").try
HTTP.get(target.string)

module URI.URL

function parse

Parses an absolute hierarchical URL with an authority.

Rejects relative references, opaque URIs, and values without a host, so a caller can use scheme and host without handling absence.

parse(text) : String -> Result<URL, URIError>
Parameters
text String
the complete URL

Returns: Result<URL, URIError> — the URL or a precise syntax error

Examples

Validating a webhook target at configuration time

let webhook = URL.parse(ENV.get("WEBHOOK_URL").or("")).try

function build

Builds and validates a URL from decoded path segments and a query value.

Pass decoded values, not pre-escaped text. The builder escapes each path segment independently, so a slash inside one value cannot accidentally become another level of the path.

build : String -> String -> [String] -> Query -> Result<URL, URIError>
Parameters
scheme String
the URL scheme, such as https
host String
the Unicode or ASCII hostname
path [String]
decoded path segments
query Query
ordered decoded query entries

Returns: Result<URL, URIError> — the encoded, validated URL

Examples

Building an API URL from an identifier supplied by a user

URL.build(
  "https",
  "api.example.com",
  ["users", userName],
  Query.from([("include", Just("profile"))])
).try

module URI.Query

function from

Builds a query while preserving order, duplicates, and bare keys.

A None value encodes as a bare key; Just("") encodes with an equals sign. This preserves the difference between ?debug and ?debug=.

from(entries) : [(String, String?)] -> Query
Parameters
entries [(String, String?)]
decoded key/value pairs

Returns: Query — the ordered query

Examples

Adding repeated filters and a bare feature flag

Query.from([
  ("tag", Just("kex")),
  ("tag", Just("beam")),
  ("debug", None)
])

function parse

Parses generic URI query encoding; remains a literal plus.

parse(text) : String -> Result<Query, URIError>
Parameters
text String
encoded query text without the leading question mark

Returns: Result<Query, URIError> — decoded entries or an invalid escape

Examples

Reading repeated filters without losing their order

let filters = Query.parse("tag=kex&tag=beam&debug").try.entries

module URI.Form

function from

Builds a form value while preserving order and duplicates.

from(entries) : [(String, String)] -> Form
Parameters
entries [(String, String)]
decoded form fields

Returns: Form — the ordered form

Examples

Preparing a login request body

Form.from([("email", email), ("password", password)]).encode

function parse

Parses form encoding where represents a space.

parse(text) : String -> Result<Form, URIError>
Parameters
text String
an application/x-www-form-urlencoded body

Returns: Result<Form, URIError> — decoded fields or an invalid escape

Examples

Reading a search field submitted by a browser

Form.parse("query=hello+world").try.entries

make URI implements Showable, Inspectable

equivalent?

Compares normalized representations rather than original spellings.

equivalent?(other)
Parameters
other URI
the URI to compare

Returns: Bool — whether the URIs identify the same normalized reference

Examples

Deduplicating differently spelled links

URI.parse("HTTP://example.com/%7Eada").try
  .equivalent?(URI.parse("http://example.com/~ada").try)

resolve

Resolves a URI reference against this absolute base.

resolve(reference)
Parameters
reference URI
the relative or absolute reference

Returns: Result<URI, URIError> — the resolved URI, or NotAbsolute when

Examples

Following a relative link

let base = URI.parse("https://example.com/docs/start").try
base.resolve(URI.parse("../api").try).try.string
# => "https://example.com/api"

inspectValue

Structural inspection is also credential-safe.

inspectValue(colors)

make URL implements Showable, Inspectable

equivalent?

Compares normalized representations rather than original spellings.

equivalent?(other)
Parameters
other URL
the URL to compare

Returns: Bool — whether the URLs normalize to the same value

resolve

Resolves a URI reference while preserving the URL invariant.

resolve(reference)
Parameters
reference URI
the relative or absolute reference

Returns: Result<URL, URIError> — the resolved absolute URL

Examples

Resolving an API pagination link

let next = URL.parse("https://api.example.com/v1/items").try
  .resolve(URI.parse("?page=2").try)
  .try

inspectValue

Structural inspection is also credential-safe.

inspectValue(colors)

make Query

make Form