Url :: # (opaque)
A validated HTTP or HTTPS URL implemented entirely in Roc.
This is deliberately stricter than a browser parser. Hosts must be ASCII DNS names, dotted-decimal IPv4 addresses, or bracketed IPv6 addresses made from hexadecimal groups with optional :: elision. IPv4-in-IPv6 and Unicode domain names are intentionally unsupported.
Parse a dynamic string as an absolute HTTP or HTTPS URL.
The input must contain an explicit scheme and authority. Its host is lowercased, default ports are removed, dot path segments are normalized, and non-ASCII path, query, and fragment bytes are percent-encoded.
from_quote : Str -> Try(Url, [BadQuotedBytes(Str)])
Convert a quoted literal to a URL using the same validation as parse.
Roc calls this automatically when a quoted literal is expected to have type Url. A rejected literal reports a descriptive BadQuotedBytes error.
parser_for : encoding -> state -> Try({ value : Url, rest : state }, err)
where [
encoding.parse_str : encoding, state -> Try({ value : Str, rest : state }, err),
encoding.invalid_value : encoding, state -> err,
]
Parse a URL from a string value supplied by a generic encoding.
encoder_for : encoding -> Url, state -> Try(state, err)
where [
encoding.encode_str : Str, state -> Try(state, err),
]
Encode a URL as its canonical string through a generic encoding.
Serialize the URL in a stable normalized ASCII form.
Scheme and DNS host names are lowercase, default ports are omitted, paths are absolute, and IPv6 addresses use eight unpadded groups.
to_inspect : Url -> Str
Render a URL for debugging and test failures.
Compare URLs by their canonical serialized representation.
Hash URLs consistently with canonical equality.
scheme : Url -> [Http, Https]
Return Http or Https.
Return the canonical host.
IPv6 brackets are omitted; to_str includes them where required.
Return an explicit non-default port.
Ports 80 for HTTP and 443 for HTTPS are canonicalized to None.
Return the absolute percent-encoded path, always beginning with slash.
Return the percent-encoded query without its leading question mark.
None and Some("") distinguish no query from a present empty query.
Return the percent-encoded fragment without its leading hash.
None and Some("") distinguish no fragment from a present empty fragment.
without_fragment : Url -> Url
Return this URL without its fragment. HTTP never transmits fragments.
Resolve a strict relative reference or absolute web URL against this URL.
Root-relative, path-relative, query-only, and fragment-only references are supported. Scheme-relative references are rejected.
append_path_segments : Url, List(Str) -> Url
Append unencoded path segments.
Each list item is one segment, so slash characters inside an item are percent-encoded rather than treated as separators.
append_query_param : Url, Str, Str -> Url
Append one application/x-www-form-urlencoded query pair.
Existing parameters, ordering, duplicate names, and the fragment are preserved.
query_pairs : Url -> List((Str, Str))
Decode the query into ordered name/value pairs.
Plus signs decode as spaces, percent escapes decode as UTF-8 bytes, parameters without equals receive an empty value, and duplicates remain.
with_query : Url, [None, Some(Str)] -> Try(Url, ParseErr)
Replace or remove the query.
Some("") produces a present empty query. The supplied query may contain Unicode but must otherwise already obey URL query syntax.
with_fragment : Url, [None, Some(Str)] -> Try(Url, ParseErr)
Replace or remove the fragment.
Some("") produces a present empty fragment. Unicode is percent-encoded.
ParseErr : [
CredentialsNotAllowed,
EmptyHost,
InternationalHostUnsupported,
InvalidCharacter(U8),
InvalidHost(Str),
InvalidIpv4(Str),
InvalidIpv6(Str),
InvalidPercentEncoding(U64),
InvalidPort(Str),
MissingAuthority,
MissingScheme,
PortOutOfRange(U64),
UnsupportedScheme(Str),
]
A reason a URL or relative reference could not be parsed.
This error set describes this module's strict HTTP/HTTPS subset. Inputs that browsers might repair, such as missing authority slashes or backslashes, are rejected instead.